OpenDirect_OOH_1-5-1_v1-2.md

OpenDirect (OOH) 1.5.1 v1.2

An OpenDirect 1.5.1 Implementation for the Out-Of-Home Industry

OpenDirect 1.5.1

The OpenDirect media trading API was devised by the OpenDirect Working Group, a working group within the IAB Technology Lab. Further details about the IAB Technology Lab can be found at: https://iabtechlab.com/working-groups/opendirect-working-group/

OpenDirect (OOH) 1.5.1

OpenDirect (OOH) is a recognised community extension of the IAB OpenDirect programmatic trading schema, particularly developed around Out-Of-Home 'Product and Availability Targeting' functions

OpenDirect enables Media Owners to apply their own sales rules to inventory deals, and make these products discoverable and purchasable directly to a Media buyer without the need for 3rd party SSP, Exchange and DSP integration or fees.

The standard uniquely accommodates the 'real world' aspects of both Classic and Digital Out-Of-Home Media (OOH) inventory in the 5 dimensions of location, delivery, distribution, investment and display prohibitions.

OpenDirect (OOH) has been developed by the members of the OOH industry organisations Outsmart and the IPAO and is endorsed by the OAAA

About Outsmart

Outsmart is the UK trade body for the Out of Home advertising industry. Members include the biggest sellers of OOH advertising in the UK: Clear Channel UK, Global, JCDecaux and Ocean Outdoor.

About the UK OOH Industry Standards Committee

The OOH Standards Committee has representation from both Outsmart and IPAO. The IPAO represents the biggest buyers of Out of Home advertising. The committee consults, develops and agrees upon standards which are required to improve the efficiency and effectiveness of the operation of Out of Home Buying and Selling

About the Technical Sub-Group

The Technical sub-group is a part of the OOH Industry Standards Committee. This group of experts sourced from Media Owners, Agencies and Specialists from the OOH Industry, were challenged to create a standard way for Media Owners/Publishers to make their inventory discoverable in a OpenDirect-compliant interface where agencies and advertisers can programmatically trade OOH inventory directly.

Contributors

Clear Channel Ben Price, Jamie Mills, Victor Porter, Karen Fornos Klein, Miles Talmey, Noopur Gosalia, Joao Baptista, Sebastiaan Schinkel

Global Dan Sharp, Luke Howard, Matt Allard, Rob Brayshaw, Denis Garcia, Olga Belousova

JCDecaux Dom Kozak, Philippa Kings, Rebecca Lee, Ioana Dima, Jack Paget

Kinetic Alex Berry, Georgina Monet, Prasaant Patel

Mediacom Nate Barker

Ocean Outdoor Angela Green, Doug Swan, Luka Djukic

Posterscope Daniel Conway, Steve Pavett, Christopher Ho, Alexandru Radu, George Popescu, Tina Hung

Rapport Paul Sambrook, Ross Wilson, Gail Williams

Talon Outdoor Anant East

Knitting Media Tim Harvey

Special Thanks to

Tim Lumb OutSmart

Gavin Lee Dentsu Aegis & Former UK OOH Standards Committee Co-Chair (IPAO)

Mungo Knot Global & UK OOH Standards Committee Co-Chair (Outsmart)

Richard Saturley World Out of Home Organisation

Contents

OpenDirect 1.5.1 v1.2

Executive Summary

OpenDirect 1.5.1 & OpenDirect (OOH) 1.5.1 Comparison Version Control Audience

1. Introduction/Overview

2. Resources

2.1 Account 2.2 Assignment 2.3 Creative 2.4 Line 2.5 Order 2.6 Organization 2.7 Product 2.8 Change Request 2.9 Stats

3. Common Objects

3.1 Address 3.2 AdvertiserBrand 3.3 Contact 3.4 ProductAvails 3.5 ProductAvailsSearch 3.6 ProductSearch 3.7 OOHProviderData 3.8 Size 3.9 OOHbject 3.10 Availability

4. Reference Data

4.1 AdFormatType 4.2 AdPosition 4.3 Availability 4.4 ContactType 4.5 Country 4.6 Currency 4.7 DeliveryType 4.8 FrequencyCapInterval 4.9 Industry 4.10 InventoryType 4.11 Language 4.12 MaturityLevel 4.13 RateType 4.14 Targeting 4.14.1 Inventory OOHbject 4.14.2 Delivery OOHbject 4.14.3 Investment OOHbject 4.14.4 Distribution OOHbject 4.14.5 Prohibitions OOHbject

5 Collection Objects

6 OpenDirect General Support Requirements

6.1 Authentication 6.2 Versioning 6.3 HTTP Error Codes/ErrorHandling 43 6.4 ErrorResponse 6.5 Data Format 6.6 Logical JSON operators 6.7 Stats (OOH Schedule & Delivery Reporting) 6.8 Paging QueryParameters

7 URIs and General Request/Response Rules

7.1 URI Summary Table 7.2 Account 7.3 Account Assignments 7.4 Account Creative 7.5 Account Orders 7.6 Account Order Lines 7.7 Organizations 7.8 Products 7.9 Change Request 7.10 Change Request Lines 7.11 Stats Reporting 7.12 Advertiser Brands 7.13 DataSources

8 OpenDirect Workflow

Appendix A: Specification Change Log

Appendix B: Minimum OpenDirect (OOH) Resources & Objects Required For An Initial Implementation

Appendix C : OOHbject Schema variation when used in the context of Product, Availability and Line operations

Executive Summary

OpenDirect

OpenDirect enables publishers to offer premium inventory using a programmatic interface that partners and vendors build according to the OpenDirect specifications.

Every organization in the industry uses some kind of interface (or a combination thereof) to manage inventory throughout the buying and selling of premium, reserved inventory. Each system is different, which means if one partner wants to integrate their system with another system, the integration is customized to that system. Further integrations all require customization, each instance consuming valuable overhead. While the overhead enables more business, cutting down on the cost of these integrations allows resources to be diverted to more important ad operations tasks.

OpenDirect provides a standard way for publishers to make their inventory available in any OpenDirect-compliant interface where agencies and advertisers can reserve and purchase inventory.

For publishers, this means that in a programmatic marketplace, publishers can make premium guaranteed inventory available to more buyers. Tech providers can offer a greater variety of premium inventory to their customers. For the industry, a marketplace that uses OpenDirect means more fluid movement of inventory while greatly reducing the overhead involved when integrating with partners.

Adoption of OpenDirect also opens the doorway to controlled access and improved tracking of inventory across systems, providing early visibility reporting and potentially reducing discrepancies down the road. While OpenDirect does not directly enable improved impression counting between parties, it does lay the foundation for opportunities to improve impression reporting between systems.

Publishers can begin using OpenDirect by modifying their systems to log Organizational IDs and accounts consistent with the specs in this document. They also need to be able to respond to API requests for inventory details as well as manage inventory in response to API requests.

Tech providers who want to use OpenDirect need to make use of the API in this spec as they design and build their interfaces for offering automated guaranteed inventory.

As OpenDirect becomes widely adopted in the marketplace, the movement of premium inventory becomes more fluid.

OpenDirect (OOH)

OpenDirect (OOH) is an extension of the OpenDirect schema, particularly around the 'Product Target' function, to accommodate the unique aspects of the 'real world' OOH inventory in the dimensions of location, delivery, distribution, investment and display prohibitions.

OpenDirect (and OpenRTB) trades with real time Audience impressions, whereas Out-Of-Home media can be sold in the wider dimensions of predefined time, share of time, physical locations as well as audience impressions.

OOH 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 advert an opportunity to see the advertising.

OpenDirect (OOH) 1.5.1 uses the concept of 'OOHbjects' which are used to discover and target the multidimensional aspect of OOH media. An OOH media owner/ publisher can use one or more OOHbjects to translate their sales policy into DealIDs or Products that can then be discovered, targeted and traded programmatically.

Creative Assignment has been omitted from the OpenDirect (OOH) 1.5.1 document as this will be addressed in OpenDirect (OOH) 2.0 using the AdCom model as described in the IAB OpenDirect 2.0 documentation for Video and OOH media support.

OpenDirect 1.5.1 & OpenDirect (OOH) 1.5.1 Comparison

A summary of the additions and extensions to OpenDirect 1.5.1 are summarised in red in the below diagram.

The extensions were created to cover five key areas

Buying Types

The OOH Industry in the UK has three main types of organizations known as Advertiser, Agency and Specialist agency who may all be involved in the campaign

Brand Identification

The OOH industry has Prohibitions around certain types of products running in certain physical locations which requires a more detailed level of granularity around Advertiser and Brand

OOH ProviderData

OOH Provider Data is used for Buyers to detail information that may be used to identify their order in a Seller's system using specific IDs or references. This would be mainly used for manually identifying orders in the event of the automated process needing manual intervention.

Stats

A method to publish the OOH display schedule generated to fulfil the campaign targeting requirements (pre-flight) and the performance of the schedule when the campaign is in flight and/or completed.

Targeting OOHbjects

A collection of targeting criteria used to discover and target the digital and physical presentation aspects of OOH media. This includes:

• 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 (Fixed 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.

Version Control

Version	Author	Date	Page	Description
0.2	Tim Harvey	16/03/20	All	First Draft of OpenDirect (OOH) 1.5.1
1.0	Tim Harvey	24/04/20	All	PDF Published Version of OpenDirect (OOH) 1.5.1 v1.0
1.1	Tim Harvey	from 12/04/20	See Github Log	Github Published Version of OpenDirect (OOH) 1.5.1 v1.1
1.2	Tim Harvey	from 08/06/21	See Github Log	Updated document featuring improvements that were worked on as organizations implemented the standard in 2021

Audience

Buy and Sell Side Tech providers can use the specifications in this document to build a system for accessing and booking OOH publisher/media-owner inventory. Tech providers may include the technical staff or partners who work with agencies, networks, exchanges, or specialty vendors that offer inventory purchasing services.

Publishers/Media-Owners also need to use this spec to make their inventory available to API requests from Tech Providers.

1. Introduction/Overview

The OpenDirect API provides a standard way for publishers to integrate with tech provider partners so that they can offer premium guaranteed inventory programmatically. Using the API, buyers can build one system that can access inventory from multiple publishers without custom integrations for each one.

Some of the features supported in OpenDirect are:

• Searching product inventory
• Determining price and availability
• Applying targeting and frequency constraints
• Creating orders and adding lines
• Uploading creative and assigning creative to lines
• Reserving and booking inventory

Additional features are added with each new update to further enable wider adoption and support the needs of the industry.

1.1 How it works

At a high level, the workflow involves establishing a relationship between buyer and publisher, setting up accounts, and placing orders on the buyer side while publisher systems respond to API requests for order placement. The following table outlines general steps for using the API: Buy

Buy Side	Sell Side
1. Establish a relationship In order to buy inventory with publishers using OpenDirect systems, buyers must first obtain an ID from the publisher that can be used in any OpenDirect system for as long as you do business with the publisher.	1. Establish a relationship To protect your inventory, buyers must first obtain an ID from you. This ID can be used in any OpenDirect compliant system for as long as you maintain a business relationship with the buyer.
2. Set up Buyers use with their publisher-obtained IDs and create accounts to begin browsing inventory and placing orders.	2. Set up Publishers create organization accounts for buyers to access in any OpenDirect system which the publisher has a working relationship.
3. Place Orders After establishing accounts in the system, buyers can begin browsing publisher inventory and adding lines to orders.	3. Respond to API Requests Once buyers are set up in their OpenDirect system(s), they can begin browsing and booking inventory. On the publisher side, this is received as API requests that publisher systems must respond to.
4. Validate Delivery of Orders Buyers can check the delivery status of In-flight and completed orders	4. Report on Order Delivery Request for order delivery progress and completion, based on the targeted metrics of the booked order, is received as API requests that publisher systems must respond to.

1.2 Authorisation

The OpenDirect API is a RESTful API that supports paging query parameters and uses OAuth to authenticate users. A publisher must support at least one "full access" user account (API credentials) per buying organization. Non-buying organizations may have optional user accounts. A publisher may support flexible permission schemes for additional user accounts.

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 or OOH 'Specialist' 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.

Third Party: A group media agency may use a specilaist buying agency to buy OOH Media. In this case the Buyer will be the specialist, and the Third Party will be the organization upon who's behalf an Order is being placed (the group media agency).

1.3 Programming Elements

For details about the programming elements that this specification defines, see the following sections.

Resources: The key objects, such as Account, Order, Line, Creative, etc. that define the OpenDirect API.

Common Objects: Defines the objects that supply field values used in one or more resources, such as Address and Contact.

Collection Objects: A list of objects that return an array of values for a field, typically provided by the publisher. For example, publisher-defined target fields (Target) and their values (TargetValue) are provided as collection objects, where Target might be 'Age' and the TargetValue would be a list of the publisher-defined age groups (18-24, 25-32, 33-39, etc.)

URIs and General Request/Response Rules : Defines the URI supported HTTP verbs (GET, POST, etc.) for each resource.

Authentication: Defines the authentication scheme that publishers must use.

Versioning: Defines the versioning scheme that publishers must use.

HTTP Error CodesError Handling: Defines the error objects that publishers must return for 400 Bad Request errors.

Reporting: Defines the reporting URIs and objects.

OpenDirect Workflow: Outlines the process for establishing an account and the calls required to create and process an order.

2 Resource Objects

The OpenDirect API is a RESTful API that supports JSON. This section uses JSON schemas to define the resource objects used by the API. For a diagram that shows the relationships between these resources, see Resource Model.

2.1 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.

Before an agency may create accounts and perform buys on behalf of the advertiser, the advertiser must give permissions to the agency. The process of giving or removing permissions is publisher-defined. Creating an account must fail if the advertiser has not given the agency permissions.

The Account owns the order.

Attribute	Description	Type
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)
ThirdPartyId	An ID that identifies the organization upon who's behalf an Order is being placed (e.g. a group media agency).	String (36)
Id	A system-generated opaque ID that uniquely identifies the account.	String (36)
Name	The name of the account. Used for display purposes.	String (36)
ProviderData	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 (1000)
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)

Account Schema: https://raw.githubusercontent.com/Outsmart-OOH/ooh_open_direct/master/schema/v1/resources/account/account_object.json

2.2 Assignment

Creative assignment not in scope for OpenDirect (OOH) 1.5.1

2.3 Creative

Creative specification is not in scope for OpenDirect (OOH) 1.5.1

2.4 Line

Line resources are included in an order and provide details about the product being booked, status, start and end dates, and other settings for the order item.

Notes: The user may update a line only if it's in the Draft state. If the line is in the Reserved or Declined state, the user may call Reset to move the line back to the Draft state in order to update the line.

Attribute	Description	Type
BookingStatus	A value that determines whether the line is booked and is capable of delivering ads. For a states , see Booking Status Values.	enum (Draft, PendingReservation, Reserved, PendingBooking, Booked, InFlight, Finished, Stopped, Cancelled, Paused, Expired, Declined, ChangePending)
Comment	User notes related to this line.	String (255)
Cost	The projected cost of the line is based on the specified targeting.	Decimal
EndDate	The date and time that the line will stop. The date and time must be specified in UTC and conform to ISO 8601. If the time is missing, 11: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.	ISO-8601
Id	A system-generated opaque ID that uniquely identifies this resource.	String (36)
Name	The line’s display name. Should be unique.	String (255)
OrderId	The ID of the order that this line belongs to.	String (36)
PostingInstructions	Posting Instructions for Classic OOH. Select one or more from list: Post No Earlier Than Start Date Post No Later Than Start Date Request Blanking	Array
ProductId	The ID of the product where the creatives run.	String (36)
ProviderData	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 (1000)
OOHProviderData	The OOHProviderData 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
ReservedExpiryDate	The date and time that the reserved inventory will expire. If the line is reserved, the expiry date must be set.	String
StartDate	The date and time that the line will start. The date and time must be specified in UTC and conform to ISO 8601. If the time is missing, 12:00 AM is assumed. The date and time must be greater than or equal to now and should be greater than or equal to the order’s start date. If the line start date is earlier than the order’s start date, the order’s start date should be moved to match the line’s start date. Both dates must be later than the present day. Start dates that are in the past may not be updated.	ISO-8601
StateChangeReason	The reason why the state was changed by the publisher. The reason must be specified if: The publisher declined the booking or reservation, The publisher or user canceled the flight.	String (255)
Targeting	The segments used to target users and determine product availability.	Object
Availability	This Object is used to return the Availability, Partial Availability and Unavailability in the event of the line reserve/booking request failing because of a change in product availability between booking states	Object

Line Schema: https://raw.githubusercontent.com/Outsmart-OOH/ooh_open_direct/master/schema/v1/resources/line/line_object.json

2.4.1 Booking Status Values

• Draft – Indicates that a draft of the line has been saved. The line may be updated only in this state. The line remains in this state until the user deletes, reserves, or books the line.
• PendingReservation – Indicates that the reservation is in progress. If approved, the state moves to Reserved; otherwise, it moves to Declined. Any user action requested in this state must fail.
• Reserved – Indicates that the inventory for the line has been reserved. Remains in this state until the user cancels, books, resets the line or the reservation expires. The ability to reserve inventory is optional. Each publisher determines the length of time that inventory may be reserved without booking before it's released. If the line is reserved, the ReservedExpiryDate must be set to the date and time that the reserved inventory will expire.
• PendingBooking – Indicates that the booking is in progress. If approved, the state moves to Booked; otherwise, it moves to Declined. Any user action requested in this state must fail.
• Booked – Indicates that the line is booked and the buyer is obligated to the terms. The line stays in this state until the user cancels the line or the line reaches its delivery window. After the line reaches its delivery window, the line moves to the InFlight state.
• InFlight – Indicates that the line is in its delivery window. The line stays in this state until the user cancels the line or the line reaches the end of its delivery window. If the line reaches the end of its delivery window, then it moves to the Finished state; otherwise, it moves to the Stopped state.
• Finished – Indicates that the line successfully completed its flight. The line remains in this state.
• Stopped – Indicates that the user or publisher cancelled the line while it was in-flight. The StateChangeReason field must specify the reason why the flight was cancelled. The line remains in this state.
• Cancelled – Indicates that the user cancelled the line while it was in the Reserved or Booked state. The line remains in this state.
• Paused – Indicates that all creative for the line have been temporarily stopped while in Inflight status. Line may return to Inflight status or be updated to the Stopped status if creative is to be cancelled.
• Expired – Indicates that the reservation expired. The line remains in this state unless the user resets the line, which moves it back to the Draft state
• Declined – Indicates that booking or reservation was declined by the publisher or failed. The line remains in this state unless the user resets the line, which moves it back to the Draft state. The StateChangeReason field must specify the reason why the booking or reservation was declined or failed.
• PendingChange – this status is to be used for all asynchronous changes other than reservation and booking.

2.5 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.

To specify the individual line item details of the order, use the LINE resource specified in section 2.5

Attribute	Description	Type
AccountId	The ID of the account that identifies the advertiser and buyer that own the order.	String (36)
AdvertiserBrandId	The id of the AdvertiserBrand being advertised	String (36)
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.	Object
Currency	The currency that all monetary properties of the order and lines are specified in. The currency is also used for billing and reporting. Values are provided using the CURRENCY reference data as specified in section 4.6.	String (3) [ISO-4217]
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.The date and time must be specified in UTC and conform to ISO 8601. If the time is missing, 11:59 PM is assumed.The end date must be later than the start date. End dates that have past cannot be updated.	ISO-8601
OrderExpiryDate	The date and time using the ISO 8601 format for when the order expires. Publisher will only hold inventory up until the date and time indicated.	ISO-8601
Id	A system-generated opaque ID that uniquely identifies this resource.	String (36)
Industry	The industry associated with the order. This industry may differ from the industry specified on the advertiser’s Organization object.	Object
Name	The order’s display name. Must be unique within the account’s list of orders.	String (100)
OrderStatus	Specifies the Status of the Order **PENDING** – The Order has not yet been approved/rejected **APPROVED** – The Order has been approved **REJECTED** – The Order has been rejected	String (36)
PreferredBillingMethod	Electronic (Default) or Postal	String (10)
PostingInstructions	Posting Instructions for Classic OOH. Select one or more from list: Post No Earlier Than Start Date Post No Later Than Start Date Request Blanking	Array
ProviderData	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 (1000)
OOHProviderData	The OOHProviderData 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
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.The date and time must be specified in UTC and conform to ISO 8601. 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.	ISO-8601

Order Schema: https://raw.githubusercontent.com/Outsmart-OOH/ooh_open_direct/master/schema/v1/resources/order/order_object.json

2.6 Organization

The organization resource may represent an advertiser or agency (buyer). The Account determines the role that the organization plays by using the organization ID in place of the BuyerId or AdvertiserId. The organization's role may vary by account. For example, the organization may be an advertiser in one account and a buyer in another. An advertiser may create one or more organizations to meet their business needs. For example, they may create a single organization and then create accounts for each brand, subsidiary, or division. Or, they may create an organization for each brand. It is up to the advertiser to determine how they use Organization and Account to meet their organizational needs.

At the moment the Sell Side creates all Organizations, this is not a schema nor API function that will be used by the Buy Side. It is up to the Sell Side to populate the Organization data according to the schema guideline. If the Organization schema is opened to the Buy Side, it is advised that the schema should then identify required fields to match Sell Side expectations.

Attribute	Description	Type
Address	The organization’s corporate headquarters address.	Object
AdvertiserBrands	Array of one or more AdvertiserBrands associated with the Organisation	Array
Contacts	A list of one or more contacts within the organization. Available contacts are provided using the CONTACT common object as specified in section 3.3. The list must contain unique contact types (for example, only one billing contact) and at least one billing contact is required.	Object
Disapproval Reason	The reason why the organization was not registered. Must be specified if Status is Disapproved.	String (255)
Fax	The organization’s fax number.	String (36)
Id	A system-generated opaque ID that uniquely identifies this resource.	String (36)
OrganizationType	The core activity that an organisation undertakes as a business e.g. advertiser, OOH Specialist or Media Agency	enum (Advertiser, OOH Specialist, Agency)
Name	The organization’s display name.	String (128)
Phone	The organization’s phone number.	String (36)
ProviderData	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 (1000)
OOHProviderData	The OOHProviderData 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	A value that indicates the current state of the approval process. The approval process confirms the organization’s identity. The following are the possible values. • Pending – The organization is under review. • Approved – The organization is approved and can create and book orders. • Disapproved – The organization’s identity could not be verified. The organization may not create and book orders. The DisapprovalReason property must specify the reason why the organization was not approved. • Limited – The organization’s identity could not be verified; however, they may create and book orders. This state may affect the products and # offered to the organization. The organization may create orders in any state (except where noted); however, they may search for available inventory or reserve and book inventory only in the Approved and Limited states.	enum (Pending, Approved, Disapproved, Limited)
Url	A URL to the organization’s website.	String (1024)
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

Organization Schema: https://raw.githubusercontent.com/Outsmart-OOH/ooh_open_direct/master/schema/v1/resources/organization/organization_object.json

2.7 Product

A Product resource identifies anything from an ad placement to a Run of Network product in the publisher's product catalogue. Values for all supported fields are provided by the publisher.

Attribute	Description	Type
ActiveDate	The date and time, in UTC, that the product may become part of the bookable inventory. Use ISO-8601 format for time and date.	ISO-8601
AdFormatTypes	A list of ad types that the product supports.	Array
AdvertiserIdAccess	List of AdvertiserIDs with access to this Product. NULL = all accounts can access this product.	Array
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 TRUE for OOH	Boolean
AvailsGroupBy	An array of OOHbjects that describe the grouped fields that that the Availability data can be returned in	Object
BasePrice	The product’s base retail price; this is not the rate card price. The actual price may be more if targeting is specified.	Decimal
BuyerIdAccess	List of BuyerIDs with access to this Product. NULL = all accounts can access this product.	Array
Currency	Identifies the currency for BasePrice and MinSpend. Values provided using CURRENCY reference data as specified in section 4.6.	String (3) [ISO-4217]
DeliveryType	The type of delivery. For example, exclusive, guaranteed or non-guaranteed. Values provided using DELIVERY TYPES reference data	Object
Description	The product’s description.	String (255)
Geometry	A list of ad format sizes that the product supports. Values provided using the SIZE common object as specified in section 3.7.	Object
Icon	URL to a thumbnail icon of the product. May be used to display next to the product in the product catalog.	String (1024)
Id	A system-generated opaque ID that uniquely identifies this resource.	String (36)
Languages	A list of creative languages that the product supports. Values provided using LANGUAGE reference data as specified in section 4.10.	Array
LeadTime	The time from the time of booking that a line that reference this product can begin running; the line’s start date must be equal to or later than today + n.	String
Name	The product’s display name. The name must be unique.	String
ReservedExpiryTime	Defines the day of the week and time of day that represents the cut off point for expiry of a Line for the Product when it is “reserved”.	ISO-8601
RetirementDate	The date and time, in UTC, that the product may be removed from the bookable inventory. Use ISO-8601 format for time and date	ISO-8601
TargetTypes	An Array of OOHbjects that identify the types of targeting that the product supports.	Object
ThirdPartyIdAccess	List of ThirdPartyIDs with access to this Product. NULL = all accounts can access this product.	Array
TimeZone	The time zone that the product runs in.	tz database time zone
Url	A URL to the specification that describes the creative requirements.	String (1024)

Product Schema: https://raw.githubusercontent.com/Outsmart-OOH/ooh_open_direct/master/schema/v1/resources/product/product_object.json

2.8 Change Request

When an order has already been placed and a change is needed, the ChangeRequest resource can be used to request a change (at Account level) and subsequently modify the order pending the approval of the change request.

The Order filter request specified in section 7.6.3 can be used to find orders that have a booking status of "PendingChange."

Attribute	Description	Type
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.	Object
Id	A system-generated opaque ID that uniquely identifies this resource.	String (36)
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 at line level)	String (36)
OOHProviderData	The OOHProviderData 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
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)
Status	Specifies the Status of the Change Request: · PENDING – The Change has not yet been approved/rejected, · APPROVED – The Change has been approved, · REJECTED – The Change has been rejected	String (36)
Webhook	URI which is called when the change is approved, rejected or modified by the Seller. URI is called with a PUT request containing Change as a JSON object.	String (1024)

Change Request Schema: TBC

2.9 Stats

See 6.7 Stats (OOH Schedule & Delivery Reporting)

3 Common Objects

The following objects are common to one or more resources. For example, the CONTACT common object is used to provide values for both the PRODUCT and ORGANIZATION resources.

3.1 Address

Defines address details for an Organization or Contact

Attribute	Description	Type
AddressLine1	The first line of the address	String (255)
AddressLine2	The optional second line of the address	String (255)
City	The name of the city in which the address is located	String (35)
State	The name of the state/province/county in which the address is located	String (35)
Country	The name of the country in which the address is located	ISO 3166-1 country code
PostalCode	The postal or zip code for the address	String (255)

Address Schema: https://raw.githubusercontent.com/Outsmart-OOH/ooh_open_direct/master/schema/v1/common/address_object.json

3.2 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 (255)
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

AdvertiserBrand Schema: https://raw.githubusercontent.com/Outsmart-OOH/ooh_open_direct/master/schema/v1/common/advertiserBrand_object.json

3.3 Contact

Defines details for an individual contact within an Organization. The following fields are a minimum requirement for a contact record:

• FirstName
• LastName
• Email 
• Type 

If a Media Owner / Publisher requires a contact to be submitted with an Order, the Media Owner must show the Agency and/or Third Party buyer how to register contacts, and if they need to exist in an Organisation.

In OpenDirect the contacts can be listed in the Organisation object, but a contact does not have to be assigned to an Organisation ID.

Attribute	Description	Type
Honorific	The contact's honorific such as Mr, Mrs	String (20)
Title	The contact’s job title	String (20)
FirstName	The contact’s first name	String (20)
LastName	The contact’s last name	String (20)
Email	The contact’s email address	String (20)
Phone	The contact’s phone number	String (20)
Type	The type of contact that this resource represents (e.g. billing, creative)	String (20)
Address	The contact’s address	Object

Contact Schema: https://raw.githubusercontent.com/Outsmart-OOH/ooh_open_direct/master/schema/v1/common/contact_object.json

3.4 ProductAvails

Defines the response to a request for product availability and # information at product Level

Attribute	Description	Type
ProductId	ID that identifies the product for which availability and # information is provided	String(36)
AccountId	The ID of the account that identifies the buyer, advertiser and any other stakeholders.	String(36)
Availability	An object that groups the inventory availbility into Available, Partially Available and Unavailable arrays of Targeting OOHbjects	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 based on OOHbject Targeting	Decimal
StartDate	The requested start date for inventory delivery	ISO-8601
EndDate	The requested end date for inventory delivery	ISO-8601

ProductAvails Schema: https://raw.githubusercontent.com/Outsmart-OOH/ooh_open_direct/master/schema/v1/common/productAvails_object.json

3.5 ProductAvailsSearch

Defines search criteria used for requesting product availability and # within the given search criteria. This object is returned at OOHbject Level based on the OOHbject targeting criteria submitted.

Attribute	Description	Type
ProductIds	A list of IDs that identify the products on which to get availability and # information	Array
Targeting	The Inventory, Delivery, Investement and Distribution OOHbject variables to be targeted for the availability request	Array [OOHbject]
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 OOHbject metrics that availability is returned as	Array [OOHbject]
Grouping	Defines the OOHbject metric that the availability output is grouped as	Array [OOHbject]
StartDate	The desired start date for inventory delivery	ISO-8601
EndDate	The desired end date for inventory delivery	ISO-8601

ProductAvailsSearch Schema: https://raw.githubusercontent.com/Outsmart-OOH/ooh_open_direct/master/schema/v1/common/productAvailsSearch_object.json

3.6 ProductSearch

The ProductSearch object is used to generate a general list of products independent of their availability. For example, an agency might be interested in looking up all products that are available in Shopping Malls to get an idea for what the options are. Alternatively, the ProductAvailsSearch returns a list of products within specified search criteria with live availability and #.

Attribute	Description	Type
Targeting	The OOHbject targeting criteria, quantities & distribution variableds to be targeted for the availability request	Object

ProductSearch Schema: https://raw.githubusercontent.com/Outsmart-OOH/ooh_open_direct/master/schema/v1/common/productSearch_object.json

3.7 OOHProviderData

The OOHProviderData 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, OOHProviderData is generated by the buyer when the order is created. At Line level, OOHProviderData 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)

OOHProviderData Schema: https://raw.githubusercontent.com/Outsmart-OOH/ooh_open_direct/master/schema/v1/common/oohProviderData_object.json

3.8 Size

Defines the height and width (in pixels) that a publisher accepts for a given resource (e.g. Product, Creative)

Attribute	Description	Type
Height	The height of accepted creative size in pixels	Integer
Width	The width of accepted creative size in pixels.	integer

Size Schema:https://raw.githubusercontent.com/Outsmart-OOH/ooh_open_direct/master/schema/v1/common/size_object.json

3.9 OOHbject

A collection of targeting criteria used to discover and target the digital and physical presentation aspects of OOH media.

Attribute	Description	Type
Name	The key objects for describing OOH 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 OOHbject is being quantified: • Frames • Audience • Investment	enum (Frames, Audience, Investment, Total)
DataSource	The identification and inclusion of third party data sources into the OOHpenDirect 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 OOHbject Metric	String (255)
TargetValues	Array of one or more values	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 TargetValue(s) that are selected if the Buyer does not specify any TargetValue(s) or the target is not selectable	String (255) or Number

Basic OOHbject Schema: https://raw.githubusercontent.com/Outsmart-OOH/ooh_open_direct/master/schema/v1/common/oohbject_object.json

See the OOHbject Example Repository for a description of the OOHbject Schema variation when used in the context of Product, Availability and Line operations.

3.10 Availability

An object that groups the inventory availbility into Available, Partially Available and Unavailable arrays of Targeting OOHbjects

Attribute	Description	Type
Status	Summary definition of the inventory described in the Targeting Array as Available Partially Available Unavailable	String
Reason	State the reason if Partially Available or Unavailable from the list Booked Optioned Excluded OutOfCharge Prohibited Manual Trade Only InvalidPeriodLength InvalidFrameID InvalidBudget InvalidPrice ClientDuplication LocationDuplication LocationJuxta	String
Comment	Free text for an availability comment	String
Context	Array of OOHbjects describing the context of any Partially Available or Unavailable status e.g. this could be a frame that is causing a duplication error	Object
Targeting	Array of OOHbjects describing the inventory that is Available, Partially Available or Unavailable statuses	Object

OOHbject Schema: https://raw.githubusercontent.com/Outsmart-OOH/ooh_open_direct/master/schema/v1/common/productAvails_Availability_object.json

3.10 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 TPIDs 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	string	Source or technology provider responsible for the set of included IDs. Expressed as a top-level domain.
name	string	Name of Source or technology provider responsible for the set of included IDs.
tpids	object array	Array of third party IDs TPID objects from the given source. Refer to 3.11 Extended Identifier UIDs
ext	object	Placeholder for exchange-specific extensions to OpenDirect.

3.11 - TPID

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	string	The identifier for the Third Party.
ext	object	Placeholder for specific extensions to this object.

4 Reference Data

This section defines the reference data that an OpenDirect API must support. Reference data provides enumerated values for a resource property. The publisher must return only those values that they support. For example, a resource, such as Order, uses Currency reference data for the currency property to supply the list of currencies that the publisher supports.

4.1 OrganizationType

Defines the types of organization involved in the OpenDirect transaction.

Property	Description	Type	Constraints
Advertiser	An organisation that is mainly playing the roles of an advertiser	String	Max 254 Characters
Specialist	An organisation whose main business is that of an OOH Specialist	String	Max 254 Characters
Agency	An organisation whose main business is that of a Media Agency	String	Max 254 Characters
Barter	An organisation whose main business is that of a Barter Company	String	Max 254 Characters

4.2 AdPosition

Not supported in the OpenDirect (OOH) 1.5.1 Schema

4.4 ContactType

Defines the possible types of roles that a Contact plays in an Order

Property	Description	Type	Constraints
Billing	The person to contact with billing inquiries	String	Max 20 characters
Buyer	The person to contact with general questions about the order	String	Max 20 characters
Creative	The person to contact if there is an issue with one of the order’s creatives	String	Max 20 characters

4.5 Country

Not supported in the OpenDirect (OOH) 1.5.1 Schema

4.6 Currency

Defines the currency that the order is going to be transacted in to ISO 4217 currency codes e.g. GBP, USD, EUR

4.7 DeliveryType

Defines the possible types of delivery

Property	Description	Type	Constraints
Exclusive	100% share of voice.	String	Max 20 characters
Guaranteed	Guaranteed delivery of all booked display and/or impressions	String	Max 20 characters
Non-Guaranteed	Non-Guaranteed delivery of all booked display and/or impressions	String	Max 20 characters

4.8 FrequencyCapInterval

Frequency is supported as a targeting attribute in the OpenDirect (OOH) 1.5.1 targeting OOHbject

4.9 Industry

Not supported in the OpenDirect (OOH) 1.5.1 Schema

4.10 InventoryType

Inventory Type is supported as a targeting attribute in the OpenDirect (OOH) 1.5.1 targeting OOHbject

4.11 Language

Not supported in the OpenDirect (OOH) 1.5.1 Schema

4.12 MaturityLevel

Not supported in the OpenDirect (OOH) 1.5.1 Schema

4.13 RateType

Rate Type is supported as a targeting attribute in the OpenDirect (OOH) 1.5.1 targeting OOHbject

4.14 Targeting

The OpenDirect criteria for targeting.

OpenDirect (and OpenRTB) trades with real time Audience impressions, whereas Out-Of-Home 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(OOH)1.5.1 uses the OpenDirect (OOH) OOHbject object to discover and target the multidimensional aspect of OOH media.

See the OOHbject Example Repository for a description of the OOHbject Schema variation when used in the context of Product, Availability and Line operations.

The use of multiple objects to describe an OOH Product are at the discretion of the media owner/publisher. The simplest OOH product could be described as a single frame with the use of the Inventory OOHbject.

The core identification structure of an OOHbject is

• Name,Type,DataSource,Target

The key Name descriptions for OOH media targeting 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 OOHbject structure allows the identification and inclusion of third party data sources into the OpenDirect (OOH) 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 include:

• 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

4.14.1 Inventory OOHbject

The Inventory Name OOHbject allows an OOH media owner to describe (and OOH media buyer to buy) their inventory in terms of Frames and Audience then define the audience metrics that are available to targeted.

Summary

Inventory,Frames,SPACE,x

As the initial implementation of OpenDirect (OOH) 1.5.1 is in the UK, this object uses 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

These classifications could be taken and used as a common format in countries/markets where no common standards currently exist.

Alternatively, the Inventory.Frames OOHbject can reference a Media Owner / Publisher's own description of inventory e.g. Inventory.Frames..TramWraps

Inventory,Audience,ROUTE,x

As the initial implementation of OpenDirect (OOH) 1.5.1 is in the UK, this object uses 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, Mediacom Outdoor, Posterscope, Rapport Worldwide and Talon Outdoor. The media owner guarantors are Clear Channel Outdoor, JCDecaux and Global.

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

Inventory,Frames,Metrics,FrameCount

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

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.

4.14.2 Delivery OOHbject

The Delivery OOHbject allows an OOH media owner to describe (and OOH media buyer to buy) how their campaign is delivered to selected inventory.

Summary

Delivery,Frames,Time,Days

If this is made available, this dynamic OOHbject 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

Delivery.Frames.Time.Days = [0,1,2,3,4,5,6] based on ISO 8601

The OOHbject field Selectable indicates if this array 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 OOHbject 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

Delivery.Frames.Time.Hours = [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]

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

This OOHbject 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

This OOHbject 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 with have a ShareOfTime value of 25

A classic paper/vinyl billboard will have a ShareOfTime value of 100

Delivery,Frames,ShareOfDisplay,Spot

This OOHbject 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)

If the product delivers the campaign within a fixed loop, the SpotBreakLength OOHbject 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

An average % share of viewed impacts across the targeted OOHbjects 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

4.14.3 Investment OOHbject

The Investment OOHbject allows an OOH media owner to describe (and OOH media buyer to buy) their inventory in terms of Frames and Audience Investment.

Summary

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

If this is made available, this dynamic OOHbject details (in terms of the local currency) the requested cost per frame price or a target cost per frame price based on the other OOHbject Product targeting values given.

Investment,Frames,Local_Currency,Fixed

If this is made available, this dynamic OOHbject details (in terms of the local currency) the requested total Product price or given total Product price based on the other OOHbject targeting values given.

Investment,Audience,Local_Currency,CPT

If this is made available, this dynamic OOHbject details (in terms of the local currency) the requested cost per thousand price or a target cost per thousand price based on the other OOHbject Product targeting values given.

Investment,Audience,Local_Currency,Fixed

If this is made available, this dynamic OOHbject details (in terms of the local currency) the requested total Product price or given total Product price based on the other OOHbject targeting values given.

4.14.4 Distribution OOHbject

The Distribution OOHbject allows an OOH media owner to describe (and OOH 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 OOHbjects, rather than the Distribution OOHbject itself.

Summary

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

This OOHbject 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 OOHbject is Flexible meaning that the targeted ShareOfDisplay and/or frame volumes will be achieved in total over the campaign flight.

e.g.

• ShareOfDisplay,Days = Fixed, the ShareOfTime and/or total Spot Frequency will be delivered over each selected Day over the campaign flight
• ShareOfDisplay,Hours = 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

This OOHbject 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 OOHbject 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 OOHbject to the targeting array determines the Audience metrics being used e.g.

• Inventory,Audeince,Metrics,Cover (percentage of the population that saw the advert)
• Inventory,Audeince,Metrics,Reach (Unique Audience Count)
• Inventory,Audeince,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

This OOHbject 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.

4.14.5 Prohibitions OOHbject

The Prohibitions OOHbject 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

This object is attached to the Product Targeting Object to expose all FrameIDs (via the Segment) which may be affected by any of the prohibitions listed.

e.g. if the product contains the 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:

Prohibitions.Frames.SPACE.Alcohol = [1234931339, 1235190735]

This is for descriptive purpose only and the master frame to prohibitions table may be managed elsewhere by the publisher/media owner.

5 Collection Objects

For GET calls that return a collection of resources, such as /accounts/{id}/orders, the response must be an object that contains an array of the requested resources. The array must be named according to the type of resource it contains. The following table identifies the property name that must be used for each collection call.

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}/orders/accounts/{id}/orders?$filter	orders	Order_Campaign_Assignment
/accounts/{id}/orders/{id}/lines/accounts/{id}/orders/lines?$filter	lines	Lines_Assignment
/products/products/search (POST)	products	Product_Assignment
/products/avails (POST)	avails	ProductAvails_Assignment
/oohbjects/dataSources/oohbjects/dataSources?filter	dataSources	Data Sources

The following shows an example response for /accounts.

{
    "Accounts": [
 
      {
         "AdvertiserId": "B7EBC7F3-FBB3-4250-99F1-8D001088434B",
         "BuyerId": "4AA837B7-1A27-421E-9DDD-CAEF1AE884B5", 
         "Id": "9B0878BE-7254-49BE-AFD4-B0A67C7C3D26"
      },
      {
         "AdvertiserId": "16B55667-37CF-4447-A79D-88E6DAC4D7C2", 
         "BuyerId": "4AA837B7-1A27-421E-9DDD-CAEF1AE884B5",
         "Id": "EAC93F5D-F448-44D6-8333-4E530D14C9DA"
      }
   ]
}

The collection object may include additional publisher-defined properties. If there are no resources to return, the array must be empty.

6 OpenDirect General Support Requirements

6.1 Authentication

Publishers must support authenticating advertiser and agency users. Publishers must use OAuth 2.0 for user authentication. Publishers must support the implicit and authorization code grant flows.

Each request must include an access_token header that is set to the user's access token. If the token is not valid, the request must fail with HTTP status code 401 Unauthorized.

6.2 Versioning

Versioning occurs at the API level and is URI based. All services that make up the API must use the same version number. The version may fall anywhere in the path before the resource and must have the form vn[.n][.n], where n is a positive integer. For example, in the URI https://\<host\>/api/v1.2.3/accounts/{id}, v1.2.3 indicates version 1.2.3 of the API.

6.3 HTTP Error Codes/ErrorHandling

The publisher must support the following HTTP status codes.

Status Code	Description
200 Ok	Return for a successful GET, POST,or PATCH request.
400 Bad Request	Return for a POST, PATCH request that contains invalid data, or when the requested action (i.e. book) is not valid.The response must include the reasons for the error. For details, see Error Response.
401 Unauthorized	Return if the user is not authorized to make the request.
404 Not found	Return if the requested resource is not found.
500 Internal server error	Return for server-related errors.

The API may support the following HTTP status codes.

Status Code	Description
302 Found	Return if the resource has moved. The Location header must include the new URI.
304 Not modified	Return for requests that include the If-None-Match header (to support ETags) and the resource has not changed.
412 Precondition failed	Return for requests that include the If-Match header (to support ETags) and the resource has changed.

6.4 ErrorResponse

If the request generates a 400 Bad Request status code, the response must contain a collection object; the collection object must contain a single field named errors. The value of errors is an array of one or more error objects. The following table defines the properties of the error object.

Attribute	Description	Type
Field	Name of the Field value that has caused the error	String
ErrorMessage	A summary of the error that occurred.	String
Availability	A detailed response in terms of Availability, Partial Availability and Unavailabiliy and Context	Object
Link	A URL to additional help text that may help the caller solve the issue.	String

Error Schema: https://raw.githubusercontent.com/Outsmart-OOH/ooh_open_direct/master/schema/v1/general/error.json

The following shows the body of an example error response.

{
    "$schema": "https://raw.githubusercontent.com/Outsmart-OOH/ooh_open_direct/master/schema/v1/general/error.json",
    "Errors": [
        {
            "Field": "AdvertiserID",
            "ErrorMessage": "Advertiser ID Not recognised",
            "Availability": [],
            "Link": ""
        },
        {
            "Field": "BuyerID",
            "ErrorMessage": "Missing",
            "Availability": [],
            "Link": ""
        }
    ]
}

6.5 Data Format

Supported mime type: application/json

6.6 Logical JSON operators

Logical AND, OR operators are supported within JSON requests as $and, $or operators. Further logical operators may be added if the Media Owner / Publisher has the capability to action such requests.

Operator	Description	Example
$and	Performs an AND operation on an array with at least two expressions and returns the document that meets all the expressions.	{"$and":[{"age":5},{"name":"Joe"}]}
:	Performs as alternative syntax to the $and operator.	{"name":"Joe","age":5}
$or	Performs an OR operation on an array with at least two expressions and returns the documents that meet at least one of the expressions.	{"$or":[{"age":4},{"name":"Joe"}]}

Reference:

https://www.ibm.com/support/knowledgecenter/SSEPGG_11.1.0/com.ibm.swg.im.dbclient.json.doc/doc/r0061295.html

https://restdb.io/docs/querying-with-the-api

6.7 Stats (OOH Schedule & Delivery Reporting)

A method to publish the OOH display schedule generated to fulfil the campaign targeting requirements (pre-flight) and the performance of the schedule when the campaign is in flight and/or completed.

The Schedule and Delivery data can be served at Flight, Week, Day, Hour and/or Spot level of granularity at the Publisher's/Media Owner's discretion.

URI	Description
/accounts/{id}/orders/{id}/lines/stats	Requests the reporting for all Lines in the Order.
/accounts/{id}/orders/{id}/lines/{id}/stats	Requests the reporting for a specified Line in an Order.

6.7.1 Reporting

Reporting header for Report arrays

Attribute	Description	Type
ReportPublishTime	The Date and Time in UTC when the Report was published	ISO-8601
ReportStartTime	The first StartTime in the Report Array	ISO-8601
ReportEndTime	The last EndTime in the Report Array	ISO-8601
Report	An Array of Report Objects	Object

Reporting Schema: https://raw.githubusercontent.com/Outsmart-OOH/ooh_open_direct/master/schema/v1/resources/stats/reporting.json

6.7.2 Report

Report header detailing the Account, Order and Orderline information for the Stats arrays

Attribute	Description	Type
AccountId	The ID of the account that identifies the buyer, advertiser and any other stakeholders.	String
OrderId	The ID of the order that the Stats belong to	String
LineId	The ID of the orderline that the Stats belong to	String
OOHProviderData	The OOHProviderData 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
Stats	An Array of playout events that can be aggregated from a single playout event to a summary of perfromance over the whole campaign period.	Object

Report Schema: https://raw.githubusercontent.com/Outsmart-OOH/ooh_open_direct/master/schema/v1/resources/stats/report.json

6.7.2 Stats

The Schedule and Delivery data served at Flight, Week, Day, Hour and/or Spot level of granularity at the Publisher's/Media Owner's discretion

Attribute	Description	Type
StartTime	The Start Time in UTC for the Stat	ISO-8601
EndTime	The End Time in UTC for the Stat	ISO-8601
FrameID	The ID of the Frame that the delivery is carried out upon	String
CreativeID	The ID of the creative file that is played out in the Spot	String
SpotLength	The amount of time the advertiser has to play their creative in - If an advertisement is on screen for this length of time, this constitutes one play	Decimel
ShareOfTime	An Average % share of total time across the dimensions reported on for the campaign (e.g. play, hour. panel, geography)	Decimel
BookedPlays	The number of times a creative (with a defined spot length) has started playing but it may not have been fully played	Decimel
DeliveredPlays	The number of times a creative (with a defined spot length) has started playing but it may not have been fully played	Decimel
Delivery	% of Delivered Plays vs Booked Plays	Decimel

Stats Schema: https://raw.githubusercontent.com/Outsmart-OOH/ooh_open_direct/master/schema/v1/resources/stats/stats.json

6.8 Paging QueryParameters

For any resource that returns lists of data, these resources should support paging. Two resource parameters—count and offset—will be required in order to support paging. If the parameters aren't included, the total number of available data might not be returned.

count: Indicates the number of desired records to be returned in the response.

offset: Indicates the starting point from which the number of records should be returned in the response. If you wish to start with the first record, you must provide 0. Always use the number prior to the record position that is desired. For example, you have 100 records and wish to return 25 per page, you would specify it this way:

count= 25, offset 0

count= 25, offset25

count= 25, offset50

count= 25, offset 75 Recommended Count Limit: 250

6.8.1 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.

Header Name: X-Total-Count

7 URIs and General Request/Response Rules

URIs are what the API uses to communicate OpenDirect resource object details between publisher and provider systems. The following list of rules apply to all resources in general, but rules specific to each resource, along with examples for requests and responses, are described in more detail in the following sections. A summary of resource URIs is provided in section 7.1.

1. If the following is true for the request, the response must not include the property.

• The Value is NULL
• There is no default value
• Its type is numeric or a string

However, if the property is an array of any type and is NULL, the response must include the property and it must be set to an empty array.

2. All POST (add operations) and PATCH requests must include the resource in the response.

3. For POSTs (add operations), ignore properties that are set to NULL. However, for PATCH, if a property is set to NULL, remove the current value.

7.1 URI Summary Table

Resource	URI	Verbs	Required
Account	/accounts	GET, POST	Yes
	/accounts/{id}	GET, PATCH	Yes
	/accounts?$filter=	GET	Yes
Assignment	/accounts/{id}/assignments	GET, POST	Yes
	/accounts/{id}/assignments/{id}	GET, PATCH, DELETE	Yes
	/accounts/{id}/assignments/{id}?disable	PATCH	Yes
	/accounts/{id}/assignments?$filter=	GET	No
	/accounts/{id}/creatives?$filter=	GET	No
Order	/accounts/{id}/orders	GET, POST	Yes
	/accounts/{id}/orders/{id}	GET, PATCH, DELETE	Yes
	/accounts/{id}/orders?$filter=	GET	YES
Lines	/accounts/{id}/orders/{id}/lines	GET, POST	Yes
	/accounts/{id}/orders/{id}/lines/{id}	GET, PATCH, DELETE	Yes
	/accounts/{id}/orders/{id}/lines/{id}?book	PATCH	Yes
	/accounts/{id}/orders/{id}/lines/{id}?reserve	PATCH	Yes
	/accounts/{id}/orders/{id}/lines/{id}?cancel	PATCH	Yes
	/accounts/{id}/orders/{id}/lines/{id}?reset	PATCH	Yes
Organizations	/organizations	GET	Yes
	/organizations/{id}	GET	Yes
	/organizations?$filter=	GET	No
Products	/products	GET	Yes
	/products/{id}	GET	Yes
	/products/search	POST	Yes
	/products/avails	POST	Yes
ChangeRequest	/accounts/{id}/changerequest	GET, POST	No
	/accounts/{id}/changerequest/{id}	GET, PATCH, DELETE	No
	/accounts/{id}/changerequest?$filter=	GET	No
	/accounts/{id}/changerequest/{id}/approve	PUT	No
	/accounts/{id}/changerequest/{id}/reject	PUT	No
ChangeRequest/Lines	/accounts/{id}/changerequest/{id}/lines	GET, POST	No
	/accounts/{id}/changerequest/lines/{id}	GET, PATCH	No
	/accounts/{id}/changerequest/lines?$filter=	GET	No
Reporting	/accounts/{id}/orders/{id}/lines/stats	GET	No
	/accounts/{id}/orders/{id}/lines/{id}/stats	GET	No
AdvertiserBrands	/advertiserbrands	GET	No
	/advertiserbrands/{id}	GET	No
	/advertiserbrands?$filter=	GET	No
DataSources	/datasources	GET	No
	/datasources/datasource	GET	No
	/datasources?$filter=	GET	No

7.1.1 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_tpids_id=1234
/organizations?eids_name=SPACE&eids_tpids_id=4567
/organizations?eids_source=https://oohspace.co.uk&eids_tpids_id=8879

Ability to retrieve all data if pagination is implemented

/brands?offset=0&count=50000
/organizations?offset=0&count=50000

7.2 Account

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.

7.2.1 /accounts

Adds an Account or gets a list of accounts that the user has access to. The response must support pagination. See Paging Query Parameters.

Verbs

GET: Gets a list of all accounts.

POST: Adds an account.

Rules

An advertiser or agency may add accounts to only the organization they own; an agency may not add accounts to an advertiser's organization.

If an advertiser wants an agency to manage an account on their behalf, the advertiser must add the account and set the account's BuyerId to the agency's organization ID.

If an agency wishes to use a third-party buyer to manage an account on their behalf, the agency must add the account and set the account's ThirdPartyId to the agency's BuyerID.

An organization may add as many accounts as needed to create a buying structure that supports their needs. For example, the organization may create a single account, an account for each region, an account for each brand, and so on.

For an advertiser, the list of accounts will include only accounts that they own. However, for an agency and a third party, the list of accounts will include the accounts that they own and the accounts that they manage on behalf of advertisers.

7.2.2 /accounts/{id}

Gets the specified Account.

Verb

GET: Gets the specified account.

Rules

The user must have permissions to perform the requested action. For example, advertisers and agencies may get the accounts that they own. In addition, an agency may get the accounts that they manage on behalf of advertisers.

7.2.3 /accounts?$filter=

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:

• AdvertiserId
• BuyerId
• ThirdPartyId

May also support getting a list of IDs.

Rules

Only an advertiser or a buyer or third-party 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.

7.2.4 Account Examples

URI	Verb	Description	Request	Response
/accounts	GET	Get a list of all accounts		GET_accounts_response.json
/accounts	POST	Media Owner creates a new account	POST_accounts_request.json	POST_accounts_response.json
/accounts/{id}	GET	Get account details by ID		GET_accounts_id_response.json
/accounts?$filter= (e.g. ?buyerId=34587)	GET	Gets a list of accounts that match the specified filter criteria		GET_accounts_response.json

7.3 Account Assignments

Account assignments associate a creative with a line. This is not currently in scope for OpenDirect (OOH) 1.5.1, with creative submission & assignment handled in the publisher/media-owner's own CMS systems.

7.4 Account Creative

Account creative holds 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. This is not currently in scope for OpenDirect (OOH) 1.5.1, with creative submission & assignment handled in the publisher/media-owner's own CMS systems.

7.5 Account Orders

Adds an Order or gets a list of orders that the user has access to. The response must support pagination. See Paging Query Parameters.

7.5.1 /accounts/{id}/orders

Verbs

GET: (required) Gets a list of all orders that belong to the account.

POST: (required) Adds an order to the account.

Rules

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 and third parties, the list will include the orders that they own and the orders that belong to accounts that they manage on behalf of advertisers.

7.5.2 /accounts/{id}/orders/{id}

Gets, updates or deletes the specified Order.

Verbs

GET: (required) Gets the specified order.

PATCH: (required) Updates the specified order.

DELETE: (required) Deletes the specified order. May delete the order only if all lines in the order are in the Draft state. Must also delete assignments that reference the line.

Rules

The user must have permissions to perform the requested action. For example, advertisers and agencies may get, update, and delete the orders that they own. In addition, an agency may get, update, and delete the orders that belong to the accounts that they manage on behalf of advertisers.

Only orders in the Draft booking state may be deleted.

7.5.3 /accounts/{id}/orders?$filter=

The response must support pagination. See Paging Query Parameters.

Verbs

GET: (optional) Gets a list of creatives that match the specified filter criteria.

• AdStatus

May support getting a list by IDs.

Rules

User should be either an advertiser or buyer who owns the orders.

7.5.4 Order Examples

URI	Verb	Description	Request	Response
/accounts/{id}/orders	GET	Reqestor gets a list array of all orders against an account id		GET_orders_response.json
/accounts/{id}/orders	POST	Media Buyer creates a new order	POST_orders_request.json	POST_orders_response.json
/accounts/{id}/orders/{id}	GET	Gets, updates or deletes the specified Order		GET_orders_id_response.json
/accounts/{id}/orders?$filter= (e.g. ?AdvertiserBrandId=73)	GET	Gets a list of creatives that match the specified filter criteria		GET_orders_response.json

7.6 Account Order Lines

Lines hold the product details that are added to an order for an account. Creative assignment not currently in scope for OpenDirect (OOH) 1.5.1.

7.6.1 /accounts/{id}/orders/{id}/lines

Adds a Line to an order or gets a list of lines that the user has access to. The response must support pagination. See Paging Query Parameters.

Verbs

GET: (required) Gets a list of all lines in the order.

POST: (required) Adds a line to the order.

Rules

An advertiser or agency or third party may add lines to orders that they own. In addition; an agency or third party 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 or third parties, the list will include the lines that they own and the lines that belong to accounts that they manage on behalf of advertisers.

7.6.2 /accounts/{id}/orders/{id}/lines/{id}

Gets, updates, or deletes the specified Line.

Verbs

GET: (required) Gets the specified line from the order.

PATCH: (required) Updates the specified line. To update a line, the line must be in the Draft state. If the line is not in Draft state (e.g. reserved or booked) the Publisher/Media Owner may allow certain fields to be updated via a PATCH such as 'OOHProviderData'

DELETE: (required) Deletes the specified line. May delete a line only if it's in the Draft state. Must also delete assignments that reference the line.

Rules

The user must have permissions to perform the requested action. For example, advertisers, agencies and third parties may get, update, and delete the Lines that they own. In addition, an agency or third party may get, update, and delete the lines that belong to the accounts that they manage on behalf of advertisers.

A line may be deleted only if it's in the Draft state. In addition, all assignments that reference the line must be deleted.

7.6.3 /accounts/{id}/orders/{id}/lines?$filter=

Description

The response must support pagination. See Paging Query Parameters.

Verbs

GET: (required) Gets a list of lines that match the specified filter criteria. The user may use OData expressions and method calls with the following Line properties:

• Name
• BookingStatus
• StartDate
• EndDate

May also support getting a list by IDs.

7.6.4 accounts/{id}/orders/{id}/lines/{id}?book

Books the line.

Verbs

PATCH: (required) Begins the booking process for the line. The booking process may be asynchronous.

To book a line, the line must:

• Be in the Draft or Reserved State
• Have available inventory

If successfully booked, the line moves to the Booked state; otherwise, it moves to Declined and sets StateChangeReason.

Rules

The user must have permissions to book the line. For example, advertisers, agencies and third parties may book Lines that they own. In addition, an agency or third party may book lines that belong to the accounts that they manage on behalf of advertisers.

Only organizations that have an Approved or Limited status may book lines.

To book a line, the line must:

• Be in the Draft or Reserved State
• Have available inventory

The booking process may be asynchronous. If asynchronous, set the BookingStatus field to PendingBooking until the line is booked or declined. If successfully booked, set the BookingStatus field to Booked; otherwise, set the BookingStatus field to Declined and specify why the request was declined in the StateChangeReason field.

7.6.5 /accounts/{id}/orders/{id}/lines/{id}?reserve

Reserves the line.

Verbs

PATCH: (required) Reserves the line. The reserve process may be asynchronous. To reserve a line, the line must be in the Draft state. If successfully reserved, the line moves to the Reserved state; otherwise, it moves to Declined and StateChangeReason is set.

Rules

The user must have permissions to reserve the line. For example, advertisers, agencies and third parties may reserve Lines that they own. In addition, an agency or third party may reserve lines that belong to the accounts that they manage on behalf of advertisers.

Only organizations that have an Approved or Limited status may reserve lines.

To reserve a line, the line must be in the Draft booking state.

The reservation process may be asynchronous. If asynchronous, set the BookingStatus field to PendingReservation until the line is reserved or declined. If successfully reserved, set the BookingStatus field to Reserved and the ReservedExpiryDate field to the date and time that the reservation expires. If the line was not reserved, set the BookingStatus field to Declined and specify why the request was declined in the StateChangeReason field.

Supporting reserve is optional.

7.6.6 /accounts/{id}/orders/{id}/lines/{id}?cancel

Cancels the line.

Verbs

PATCH: (required) Cancels the line. To cancel a line, the line must be in the Reserved, Booked, or InFlight state.

If successfully cancelled, the line moves to the Cancelled state with a StateChangeReason comment set. If the cancellation is not approved when in InFlight state, the line may be stopped or paused.

Rules

The user must have permissions to cancel the line. For example, advertisers, agencies and third parties may cancel Lines that they own. In addition, an agency or third party may cancel lines that belong to the accounts that they manage on behalf of advertisers.

To cancel a line, the line must be in the Reserved, Booked, or InFlight state. If successfully cancelled, set the BookingStatus field to Cancelled. If the previous status was InFlight, set the StateChangeReason comment field as appropriate (for example, "User canceled").

7.6.7 /accounts/{id}/orders/{id}/lines/{id}?reset

Moves the line back to the Draft state.

Verbs

PATCH: (required) Resets a line back to the Draft state. To reset a line, the line must be in the Reserved, Expired or Declined state.

Rules

The user must have permissions to reset the line. For example, advertisers, agencies and third parties may reset Lines that they own. In addition, an agency or third party may reset lines that belong to the accounts that they manage on behalf of advertisers.

To reset a line, the line must be in the Reserved, Declined, or Expired booking state. If successfully reset, set the BookingStatus field to Draft and reset the StateChangeReason field.

7.6.8 Example Account Order Lines

URI	Verb	Description	Request	Response
/accounts/{id}/orders/{id}/lines	POST	Create order line targeted by Frames, Days, ShareOfTime and Spot Length	POST_lines_request.json	POST_lines_response.json
/accounts/{id}/orders/{id}/lines/{id}	GET	Gets the specified Line		GET_lines_id_response.json
/accounts/{id}/orders/{id}/lines?$filter=	GET	Gets a list of lines that match the specified filter criteria		GET_lines_response.json
/accounts/{id}/orders/{id}/lines/{id}?book	PATCH	Books the line		PATCH_lines_id_response_book.json
/accounts/{id}/orders/{id}/lines/{id}?reserve	PATCH	Reserves the line		PATCH_lines_id_response_reserve.json
/accounts/{id}/orders/{id}/lines/{id}?cancel	PATCH	Cancels the line		PATCH_lines_id_response_cancel.json
/accounts/{id}/orders/{id}/lines/{id}?reset	PATCH	Moves the line back to the Draft state		PATCH_lines_id_response_reset.json

7.7 Organizations

Organizations are used to define a group of users. A unique ID is generated for each organization and organization IDs are used to identify the buyer and the advertiser for an account.

7.7.1 /organizations

Gets a list of Organizations that the user has access to. The response must support pagination. See Paging Query Parameters.

Verbs

GET: (required) Gets a list of all organizations that the user has access to. The list may contain both advertiser, agency and third-party organizations depending on the caller's access. For example, if the caller is an advertiser, the list might contain only the advertiser's organization objects; however, if the caller is an agency, the list will contain the agency's organization objects and the organization objects of the advertisers whose accounts that they manage.

Rules

The list will contain a single organization for advertisers; however, for agencies, the list will include the agency's organization and the organizations of the advertisers whose accounts they manage

7.7.2 /organization/{id}

Gets or updates the specified organization.

Verbs

GET: (required) Gets the specified organization.

PATCH: (required) Updates the specified organization. The caller must have permissions to update the organization. For example, an advertiser, agency or third party may update their organization object but an agency may not update an advertiser's Organization object.

Rules

The user must have permissions to perform the requested action. For example, advertisers and agencies may get and update the Organization that they own; however, an agency may only get the organization of the advertisers whose accounts they manage.

An agency or third party may not update an advertiser's organization.

7.7.3 /organizations?$filter=

The response must support pagination. See Paging Query Parameters.

Verbs

GET: (optional) Gets a list of organizations that match the specified filter criteria. The user may use OData expressions and method calls with the following Organization properties:

• Name
• Status
• One or more Organization IDs

7.7.4 Organization Examples

URI	Verb	Description	Request	Response
/organizations	POST	Media Owner creates new Organization	POST_organizations.json	POST_organizations_response.json
/organizations	GET	A list array of all organizations available to the requestor		GET_organizations_response.json
/organizations/{id}	GET	Gets the specified organization		GET_organizations_id_response.json
/organizations/{id}	PATCH	Contact updated within an existing organization ID	PATCH_organizations_request.json	PATCH_organizations_response.json
/organizations?$filter= (e.g.?Status=Approved)	GET	Gets a list of organizations that match the specified filter criteria		GET_organizations_response.json

7.8 Products

Products are defined by the publisher with details as specified in the Product object.

7.8.1 /products

Gets the list of Products from the product catalogue. The response must support pagination. See Paging Query Parameters.

Verbs

GET: (required) Gets a list of all products from the publisher's product catalog.

Rules

Only buyers/advertisers/third parties who have obtained an Organization ID and Account ID (Buyer ID/Advertiser ID) from the publisher shall issue this request. Requests from buyers, advertisers and third parties who do not have the publisher obtained IDs shall return an error (define error code and/or message).

7.8.2 /product/{id}

Gets the specified Product from the product catalog.

Verbs

GET: (required) Gets the specified product from the publisher's product catalogue.

Rules

Only the buyers/advertisers/third parties who have obtained an Organization ID and Buyer ID/Advertiser ID/Third Party ID from the publisher shall issue this request. The ID issued should be a valid product id previously retrieved from the publisher, for example, with /products. Invalid IDs should return an error (define error code/message)

7.8.3 /products/search

Gets a list of Products from the product catalog that matches the specified filter criteria (see ProductSearch). The response must support pagination. See Paging Query Parameters.

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.

Rules

Logical JSON operators are supported in this request as defined in Section 6.6

7.8.4 /products/avails

Gets # and avails information (see ProductAvails) for the specified products (see ProductAvailsSearch). The response must support pagination. See Paging Query Parameters.

Verbs

POST: (required) Gets the availability and # 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).

Rules

Only organizations that have an Approved or Limited status may search for avails.

Logical JSON operators are supported in this request as defined in Section 6.6

7.8.5 Product Examples

URI	Verb	Description	Request	Response
/products	GET	Gets a list of all products available to the requestor. This product array of 1 product is described in terms of frames, type, format, environment, buyable days, share of time, spot, distribution, age, sex, affluence, audience metric and prohibitions.		GET_products_response.json
/products/{id}	GET	Gets the specified product from the publisher’s product catalogue		GET_products_id_response.json
/products/search	POST	Search request against the available product catalouge for products that have inventory meeting the criteria of moving digital image, 6 sheet format, in a railstation enivrionment with a creative spot length of 5 seconds	POST_products_search_request.json
/products/avails	POST	Example of using the $and logic when performing an availability search to check availbility of one array of frames at 10% ShareOfTime and a different array of frames at 20% ShareOfTime. All $ands listed	POST_avails_(and)_request_001.json	POST_avails_(and)_reponse.json
/products/avails	POST	Example of using the $and logic when performing an availability search to check availbility of one array of frames at 10% ShareOfTime and a different array of frames at 20% ShareOfTime. $ands appear only at array level	POST_avails_(and)_request_002.json	POST_avails_(and)_reponse.json
/products/avails	POST	Example of using the $and logic when performing an availability search to check availbility of one array of frames at 10% ShareOfTime and a different array of frames at 20% ShareOfTime. $ands not typed as they are implied if mulitple arrays are present	POST_avails_(and)_request_003.json	POST_avails_(and)_reponse.json
/products/avails	POST	Availability being checked against a product by Frames and Impacts by an age, sex and affluence profile. Availability required at frame level for ShareOfTime, Impacts and Price for the time period given.	POST_avails_(audience)_request.json	POST_avails_(audience)_response.json
/products/avails	POST	Availability being checked against a product by Frames by targeted Days, ShareOfTime and Spot length. Availability required at frame level for ShareOfTime, Impacts and Price for the time period given.	POST_avails_(frames)_request.json	POST_avails_(frames)_response.json
/products/avails	POST	Frames by TV Area with Target Reach and Frequency	POST_avails_(regions_targets)_req.json

7.9 Change Request

Change requests are used to make a change to the order.

7.9.1 /accounts/{id}/changerequest

Gets all change requests for an account.

Verbs

POST: Adds a change request to the account.

GET: Gets a list of all change requests that belong to the account.

7.9.2 /accounts/{id}/changerequest/{id}

Gets a specified change request.

Verbs

GET: Gets the specified change request.

PATCH: Updates the specified change request.

DELETE: Deletes the specified change request. May delete the change request only if the request is in a "PENDING" state.

7.9.3 /accounts/{id}/changerequest?$filter=

Searches for change requests.

Verbs

GET: Gets a list of change requests that match the specified filter criteria. The user may use OData expressions and method calls with the following Order properties.

• Status
• OrderId

May support getting a list by IDs.

7.9.4 /accounts/{id}/changerequest/{id}/approve

Approves a change request for an account.

Verbs

PUT

7.9.5 /accounts/{id}/changerequest/{id}/reject

Rejects a change request for an account.

Verbs

PUT

7.9.6 Change Request Examples

URI	Verb	Description	Request	Response
/accounts/{id}/changerequest	POST	Adds a change request to the account
	GET	Gets a list of all change requests that belong to the account
/accounts/{id}/changerequest/{id}	GET	Gets the specified change request
	PATCH	Updates the specified change request
	DELETE	Deletes the specified change request. May delete the change request only if the request is in a PENDING state
/accounts/{id}/changerequest?$filter=	GET	Gets a list of change requests that match the specified filter criteria. The user may use OData expressions and method calls with the following Order properties
/accounts/{id}/changerequest/{id}/approve	PUT	Approves a change request for an account
/accounts/{id}/changerequest/{id}/reject	PUT	Rejects a change request for an account

7.10 Change Request Lines

Change requests at the line level for an order.

7.10.1 /accounts/{id}/changerequest/{id}/lines

Gets all change requests for a specified line.

Verbs

GET: Gets a list of all lines in the change request.

POST: Adds a line to the change request.

7.10.2 /accounts/{id}/changerequest/{id}/lines/{id}

Gets a specified change request at the line level for an order.

Verbs

GET: Gets the specified line from the change request.

PATCH: Updates the specified line in the change request. To update a line, the line must be in the Pending state.

DELETE: Deletes the specified line from the change request. May delete a line only if it's in the Pending state. Must also delete assignments that reference the line.

7.10.3 /accounts/{id}/changerequest/lines?$filter=

Searches for lines that have a ChangeRequestPending status within a specified account.

Verbs

GET: Gets a list of lines that match the specified filter criteria. The user may use OData expressions and method calls with the following Line properties.

• Name
• StartDate
• EndDate

May support getting a list by IDs.

7.10.4 Change Request Lines Examples

URI	Verb	Description	Request	Response
/accounts/{id}/changerequest/{id}/lines	GET	Gets a list of all lines in the change request
	POST	Adds a line to the change request
/accounts/{id}/changerequest/{id}/lines/{id}	GET	Gets the specified line from the change request
	PATCH	Updates the specified line in the change request. To update a line, the line must be in the Pending state
	DELETE	Deletes the specified line from the change request. May delete a line only if it's in the Pending state. Must also delete assignments that reference the line
/accounts/{id}/changerequest/lines?$filter=	GET	Gets a list of lines that match the specified filter criteria. The user may use OData expressions and method calls with the following Line properties

7.11 Stats (Reporting)

Reporting occurs at the line level. The Media Owner / Publisher may support the following POST calls to generate a spot, impacts time and spend served report.

7.11.1 /accounts/{id}/orders/{id}/lines/stats

Aggregates the frame count, spot plays, share of time, impacts served and spend for all lines in the order

Verbs

POST

Rules

Only organizations that have an Approved or Limited status may retrieve performance stats

7.11.2 /accounts/{id}/orders/{id}/lines/{id}/stats

Aggregates the frame count, spot plays, share of time, impacts served and spend in the specified line.

Verbs

POST

Rules

Only organizations that have an Approved or Limited status may retrieve performance stats

7.11.3 Classic OOH Reporting JSON Example Response

{
    "$schema": "https://raw.githubusercontent.com/Outsmart-OOH/ooh_open_direct/master/schema/v1/resources/stats/reporting.json",
    "ReportPublishTime": "2020-12-24T00:00:00.000Z",
    "ReportStartTime": "2020-12-09T00:00:00.000Z",
    "ReportEndTime": "2020-12-22T00:00:00.000Z",
    "Report": [{
        "AccountId": "23873345",
        "OrderId": "3479",
        "LineId": "7",
        "OOHProviderData": [
            "PO7567"
        ],
        "Stats": [
            {
                "StartTime": "2020-12-09T00:00:00Z",
                "EndTime":"2020-12-22T00:00:00Z",
                "FrameID":"1234159856",
                "CreativeID":"adfgj123"
            },
            {
                "StartTime": "2020-12-09T00:00:00Z",
                "EndTime":"2020-12-22T00:00:00Z",
                "FrameID":"1234159857",
                "CreativeID":"adfgj123"
            }
        ]
    }]
}

7.11.4 Digital OOH Reporting JSON Example Response

{
    "$schema": "https://raw.githubusercontent.com/Outsmart-OOH/ooh_open_direct/master/schema/v1/resources/stats/reporting.json",
    "ReportPublishTime": "2020-12-20T00:00:00.000Z",
    "ReportStartTime": "2020-12-09T00:00:00.000Z",
    "ReportEndTime": "2020-12-10T01:00:00.000Z",
    "Report": [{
        "AccountId": "23873345",
        "OrderId": "3479",
        "LineId": "8",
        "OOHProviderData": [
            "PO7567"
        ],
        "Stats": [
            {
                "StartTime": "2020-12-09T00:00:00Z",
                "EndTime": "2020-12-09T00:00:10Z",
                "FrameID": "1234158956",
                "CreativeID": "capad653"
            },
            {
                "StartTime": "2020-12-09T00:02:00Z",
                "EndTime": "2020-12-09T00:02:10Z",
                "FrameID": "1234158956",
                "CreativeID": "capad653"
            },
            {
                "StartTime": "2020-12-09T00:03:00Z",
                "EndTime": "2020-12-09T00:03:10Z",
                "FrameID": "1234158956",
                "CreativeID": "capad653"
            },
            {
                "StartTime": "2020-12-09T00:04:00Z",
                "EndTime": "2020-12-09T00:04:10Z",
                "FrameID": "1234158956",
                "CreativeID": "capad653"
            },
            {
                "StartTime": "etc",
                "EndTime": "etc",
                "FrameID": "etc",
                "CreativeID": "etc"
            }
        ]
    }]
}

7.12 Advertiser Brands

Advertiser Brands are related to each Advertiser Organization are used to add information to a Product Availability request and Order to ensure that any booking prohibitions can be upheld.

7.12.1 /advertiserbrands

Gets a list of advertiserbrands in the Media Owner / Publisher sell side system. The response must support pagination. See Paging Query Parameters.

Verbs

GET: (required) Gets a list of all Advertiser Brands

7.12.2 /advertiserbrands/{id}

Gets a specified Advertiser Brand.

Verbs

GET: (required) Gets the specified Advertiser Brand.

7.12.3 /advertiserbrands?$filter=

The response must support pagination. See Paging Query Parameters.

Verbs

GET: (optional) Gets a list of Advertiser Brands that match the specified filter criteria. The user may use OData expressions and method calls with the following Organization properties:

• Name
• OrganizationId
• One or more AdvertiserBrandIds
• One or more ThirdPartyIds
• ThirdPartyDataSource

7.12.4 Advertiser Brand Examples

URI	Verb	Description	Request	Response
/advertiserbrands	GET	(required) Gets a list of all Advertiser Brands
/advertiserbrands/{id}	GET	(required) Gets the specified Advertiser Brand
/advertiserbrands?$filter=	GET	(optional) Gets a list of Advertiser Brands that match the specified filter criteria

7.13 DataSources

DataSources lists all targetable OOHbjects in the sell side system that are defined using third party DataSources

7.13.1 /datasources

Gets a list of all third party defined OOHbjects in the sell side system

Verbs

GET: (required) Gets a list of all DataSourced OOHbjects in the sell side system

7.13.2 /datasources/{datasource}

Gets a specified list of targetable OOHbjects by DataSource.

Verbs

GET: (required) Gets OOHbjects by the specified DataSource.

7.13.3 /datasources?$filter=

The response must support pagination. See Paging Query Parameters.

Verbs

GET: (optional) Gets a list of OOHbjects that match the specified filter criteria. The user may use OData expressions and method calls with the following Organization properties:

• Name
• Type
• Target

7.13.4 Datasource Examples

URI	Verb	Description	Request	Response
/datasources	GET	(required) Gets a list of all DataSourced OOHbjects in the sell side system
/datasources/{id}	GET	(required) Gets OOHbjects by the specified DataSource
/datasources?$filter=	GET	(optional) Gets a list of OOHbjects that match the specified filter criteria

8 OpenDirect Workflow

The following describes the calls that a client would make to get product avails and #, create an order and add lines to it, upload creatives and associate them with a line, and get a performance report. For a diagram that shows the flow, see 8.12.1 Workflow Diagram.

8.1 Onboarding a Provider

A provider is a business that develops the platform and interface that agencies and advertisers use to buy premium guaranteed ad inventory from the publisher. Onboarding the provider is a manual process that is dependent on the publisher assigning IDs to agencies and advertisers and creating accounts for them to access.

8.2 Adding an Agency Organization

Agencies # directly with the publisher. The process is publisher-defined and varies by publisher. Once an organization has been added for the agency, the agency may create organizations for their advertising clients. Each user within an organization should have their own credentials.

8.3 Adding A Third Party Organization

Third parties # directly with the publisher. The process is publisher-defined and varies by publisher. Once an organization has been added for the agency, the third party may create organizations for their advertising clients. Each user within an organization should have their own credentials.

8.4 Adding an Advertiser Organization

Advertisers may # directly with the publisher, or an agency may represent the advertiser. Once an organization has been added for the advertiser, the advertiser may create one or more organizations. For example, they may create a single organization and then create accounts for each brand, subsidiary, or division. It is up to the advertiser to determine how they use Organization and Account to meet their organizational needs.

Each user in an organization should have their own credentials.

8.5 Getting an OAuth 2.0 Access Token

Providers must use OAuth 2.0 to authenticate the user. Each API call requires an AccessToken header that is sent to the OAuth access token.

The provider may choose to use either the implicit grant flow or authorization code grant flow depending on their usage. For one time or short-term access, use the implicit grant flow. The token is short lived and will expire in minutes or seconds as determined by the authentication service. Web applications should not use the implicit flow.

For repeat or long term access, use the authorization code grant flow. The authentication service returns an access token, refresh token, and expiration time. Before the access token expires, use the refresh token to get a new access token.

8.6 Adding an Account

An advertiser may create one or more accounts based on how they organize their buys. For example, they could create accounts for each brand, subsidiary, or division. The account associates the buyer with an advertiser. If the advertiser represents itself, the account identifies the advertiser as also the buyer (the organization for both advertiser and buyer is the same).

An agency that acts on behalf of the advertiser must have permission to do so. The process of granting an agency permission to manage an advertiser's accounts is publisher-defined.

In addition to defining the relationship between the advertiser and buyer, an account also owns Order and Creative objects.

To create an account, POST a request to /accounts. The body of the request is an Account resource object. The Account object contains the buyer's ID and the advertiser's ID. The response includes the Location header that contains the URI to the new account.

8.7 Get Product Inventory, Availability and #

The following provides several options for getting product inventory details. Typically, you'd use the first two options to present a product catalog and the last option to add and book a line.

To get a product catalog to display to the user, send a GET request to /products. The response includes a collection object that contains an array of Product objects. The Product object contains the product's base rate and estimated daily impressions (for example, hundreds of thousands). Providers should not use the avails search method (option 3) to determine estimated avails.

• To get a specific product from the catalog, send a GET request to /products/{id}. The response contains a Product object.

To search the product catalog, send a POST request to /products/search. 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.

To get product availability and # 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 a media buyer, 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 # 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.

8.8 Creating an Order

An order is the parent container for lines. To add an order, send a POST request to /accounts/{id}/orders. The body of the request is an Order object, which specifies directional start and end dates, estimated budget, currency, and preferred billing method. The response includes the Location header that contains the URI to the new order.

8.9 Adding Lines to the Order

A line specifies the ad product to book, quantity, targeting details, and a date range of when the line runs. To add a line to the order, send a POST request to /accounts/{id}/orders/{id}/lines. The body of the request is a Line resource object. Typically, the client should specify the same details on the line that were used to search for product availability.

The response includes the Location header that contains the URI to the new line. The state of the line is Draft.

The line may be updated only in the Draft state. To update a line, send a PATCH request to /accounts/{id}/orders/{id}/lines/{id}.

8.10 Uploading a Creative and Assigning It to a Line

Not supported in OpenDirect (OOH) 1.5.1

8.11 Reserving, Booking, and Canceling a Line

To reserve, book, or cancel a line, send a PATCH request to the following URIs, respectively.

/accounts/{id}/orders/{id}/lines/{id}?reserve

/accounts/{id}/orders/{id}/lines/{id}?book

/accounts/{id}/orders/{id}/lines/{id}?cancel

Each call initiates a process to perform the work. To determine whether the request succeeded, send a GET request to /accounts/{id}/orders/{id}/lines/{id} to get the specified line. Access the BookingStatus property to verify that the status changed accordingly. For example, if the request was reserve, confirm that BookingStatus is Reserved. If the reservation or booking process failed, the status will be Declined. To determine why the request was declined, access the StateChangeReason property.

8.12 Diagrams

The following diagrams illustrate key aspects of OpenDirect workflow and system dependencies.

8.12.1 Publisher Workflow Diagram

The following diagram outlines the publisher workflow.

8.12.2 Agency and Advertiser Workflow Diagram

The following diagram outlines the workflow for creating an order.

8.12.3 Availability to Orderline Workflow Diagram

The following diagram outlines the workflow for going from an availability check to creating an orderline (the diagram assumes an order has already been created for an orderline to be assigned to)

8.12.4 Booking State Diagram

The following diagram shows the state changes of a Line resource. For details about each state, see BookingStatus.

8.12.5 Resource Model Diagram

The following diagram shows the relationships between the OpenDirect resources. This model allows a buyer to work with many advertisers and an advertiser to work with many buyers. If the advertiser does their own buying, they'd be both the advertiser and the buyer. For details about the resource objects, see Resources.

Appendix A : Specification Change Log

This appendix serves as an index of specification changes. These changes pertain only to the substance of the specification and not routine document formatting, organization, or content without technical impact.

Appendix B : Minimum OpenDirect (OOH) Resources & Objects Required For An Initial Implementation

The OpenDirect (OOH) standard is designed to make an OOH Media Owner's existing trading tools and methods accessible to programmatic direct buyers.

The OpenDirect (OOH) standard is not about telling media owners how to trade, nor how to create key trading tools such as allocation and # engines.

The table below summarises the OpenDirect (OOH) Resources, Common Objects and Targeting OOHbjects required to achieve a basic implementation of OpenDirect (OOH) 1.5.1 based on a Media Owner's existing trading capabilities and trading tools.

Appendix C : OOHbject Schema variation when used in the context of Product, Availability and Line operations

OOHbject URI Usage	Schema Referenced	Schema Referenced	Schema Referenced	Schema Referenced	Schema Referenced
GET_lines_id_response	uris/ lines/ lines_response.json	resources/ line/ line_object.json	common/ targetTypes_array_line.json	common/ OOHbject/ line/ delivery.json distribution.json inventory.json investment.json prohibitions.json
GET_lines_response	uris/ lines/ lines_collection_response.json	resources/ line/ line_object.json	common/ targetTypes_array_line.json	common/ OOHbject/ line/ delivery.json distribution.json inventory.json investment.json prohibitions.json
GET_products_id_response	uris/ products/ products_response.json	resources/ product/ product_object.json	common/ targetTypes_array_product	common/ OOHbject/ product/ delivery.json distribution.json inventory.json investment.json prohibitions.json
GET_products_response	uris/ products/ products_collection_response.json	resources/ product/ product_object.json	common/ targetTypes_array_product	common/ OOHbject/ product/ delivery.json distribution.json inventory.json investment.json prohibitions.json
PATCH_lines_id_response	uris/ lines/ lines_response.json	resources/ line/ line_object.json	common/ targetTypes_array_line.json	common/ OOHbject/ line/ delivery.json distribution.json inventory.json investment.json prohibitions.json
POST_avails_request	uris/ products/ products_avails_request.json	common/ productAvailsSearch_object.json	common/ targetTypes_array_avails.json	common/ OOHbject/ avails/ delivery.json distribution.json inventory.json investment.json prohibitions.json
POST_avails_response	uris/ products/ products_avails_collection_response.json	common/ productAvails_object.json	common/ productAvails_Availability_object.json	common/ targetTypes_array_line.json	common/ OOHbject/ line/ delivery.json distribution.json inventory.json investment.json prohibitions.json
POST_lines_request	uris/ lines/ lines_request.json	resources/ line/ line_object.json	common/ targetTypes_array_line.json	common/ OOHbject/ line/ delivery.json distribution.json inventory.json investment.json prohibitions.json
POST_lines_response	uris/ lines/ lines_response.json	resources/ line/ line_object.json	common/ targetTypes_array_line.json	common/ OOHbject/ line/ delivery.json distribution.json inventory.json investment.json prohibitions.json
POST_products_search_request	uris/ products/ products_search_request.json	common/ productSearch_object.json	common/ targetTypes_array_avails.json	common/ OOHbject/ avails/ delivery.json distribution.json inventory.json investment.json prohibitions.json
GET_datasources_response	uris/ datasources/ datasources_collection_response.json	common/ dataSource_object.json	common/ targetTypes_array.json	common/ oohbject_object.json

OpenDirect 1.5.1 © 2016 Interactive Advertising Bureau, OpenDirect (OOH) 1.5.1 and OOHbjects © OutSmart and IPAO March 2020