REST Resource: accounts.proposals

Resource: Proposal

Represents a proposal in the Marketplace. A proposal is the unit of negotiation between a seller and a buyer and contains deals which are served.

Note: You can't update, create, or otherwise modify Private Auction deals through the API.

Fields are updatable unless noted otherwise.

JSON representation 
{
  "proposalId": string,
  "updateTime": string,
  "proposalRevision": string,
  "deals": [
    {
      object (Deal)
    }
  ],
  "originatorRole": enum (BuyerSellerRole),
  "seller": {
    object (Seller)
  },
  "buyer": {
    object (Buyer)
  },
  "billedBuyer": {
    object (Buyer)
  },
  "displayName": string,
  "proposalState": enum (ProposalState),
  "isRenegotiating": boolean,
  "buyerPrivateData": {
    object (PrivateData)
  },
  "sellerContacts": [
    {
      object (ContactInformation)
    }
  ],
  "buyerContacts": [
    {
      object (ContactInformation)
    }
  ],
  "privateAuctionId": string,
  "isSetupComplete": boolean,
  "lastUpdaterOrCommentorRole": enum (BuyerSellerRole),
  "notes": [
    {
      object (Note)
    }
  ],
  "termsAndConditions": string
}
Fields
proposalId

string

Output only. The unique ID of the proposal.
updateTime

string (Timestamp format)

Output only. The time when the proposal was last revised.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
proposalRevision

string (int64 format)

Output only. The revision number for the proposal. Each update to the proposal or the deal causes the proposal revision number to auto-increment. The buyer keeps track of the last revision number they know of and pass it in when making an update. If the head revision number on the server has since incremented, then an ABORTED error is returned during the update operation to let the buyer know that a subsequent update was made.
deals[]

object (Deal)

The deals associated with this proposal. For Private Auction proposals (whose deals have NonGuaranteedAuctionTerms), there will only be one deal.
originatorRole

enum (BuyerSellerRole)

Output only. Indicates whether the buyer/seller created the proposal.
seller

object (Seller)

Reference to the seller on the proposal.

Note: This field may be set only when creating the resource. Modifying this field while updating the resource will result in an error.
buyer

object (Buyer)

Reference to the buyer on the proposal.

Note: This field may be set only when creating the resource. Modifying this field while updating the resource will result in an error.
billedBuyer

object (Buyer)

Output only. Reference to the buyer that will get billed for this proposal.
displayName

string

The name for the proposal.
proposalState

enum (ProposalState)

Output only. The current state of the proposal.
isRenegotiating

boolean

Output only. True if the proposal is being renegotiated.
buyerPrivateData

object (PrivateData)

Private data for buyer. (hidden from seller).
sellerContacts[]

object (ContactInformation)

Output only. Contact information for the seller.
buyerContacts[]

object (ContactInformation)

Contact information for the buyer.
privateAuctionId

string

Output only. Private auction ID if this proposal is a private auction proposal.
isSetupComplete
(deprecated)

boolean

Output only. True, if the buyside inventory setup is complete for this proposal.
lastUpdaterOrCommentorRole

enum (BuyerSellerRole)

Output only. The role of the last user that either updated the proposal or left a comment.
notes[]

object (Note)

Output only. The notes associated with this proposal.
termsAndConditions

string

Output only. The terms and conditions set by the publisher for this proposal.

Deal

A deal represents a segment of inventory for displaying ads on. A proposal can contain multiple deals. A deal contains the terms and targeting information that is used for serving.

JSON representation 
{
  "dealId": string,
  "proposalId": string,
  "createTime": string,
  "updateTime": string,
  "createProductId": string,
  "createProductRevision": string,
  "displayName": string,
  "buyerPrivateData": {
    object (PrivateData)
  },
  "dealTerms": {
    object (DealTerms)
  },
  "webPropertyCode": string,
  "sellerContacts": [
    {
      object (ContactInformation)
    }
  ],
  "availableStartTime": string,
  "availableEndTime": string,
  "description": string,
  "targetingCriterion": [
    {
      object (TargetingCriteria)
    }
  ],
  "targeting": {
    object (MarketplaceTargeting)
  },
  "creativeRestrictions": {
    object (CreativeRestrictions)
  },
  "externalDealId": string,
  "syndicationProduct": enum (SyndicationProduct),
  "creativePreApprovalPolicy": enum (CreativePreApprovalPolicy),
  "creativeSafeFrameCompatibility": enum (CreativeSafeFrameCompatibility),
  "dealServingMetadata": {
    object (DealServingMetadata)
  },
  "programmaticCreativeSource": enum (ProgrammaticCreativeSource),
  "deliveryControl": {
    object (DeliveryControl)
  },
  "isSetupComplete": boolean
}
Fields
dealId

string

Output only. A unique deal ID for the deal (server-assigned).
proposalId

string

Output only. ID of the proposal that this deal is part of.
createTime

string (Timestamp format)

Output only. The time of the deal creation.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
updateTime

string (Timestamp format)

Output only. The time when the deal was last updated.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
createProductId

string

The product ID from which this deal was created.

Note: This field may be set only when creating the resource. Modifying this field while updating the resource will result in an error.
createProductRevision

string (int64 format)

Optional. Revision number of the product that the deal was created from. If present on create, and the server productRevision has advanced since the passed-in createProductRevision, an ABORTED error will be returned.

Note: This field may be set only when creating the resource. Modifying this field while updating the resource will result in an error.
displayName

string

The name of the deal.
buyerPrivateData

object (PrivateData)

Buyer private data (hidden from seller).
dealTerms

object (DealTerms)

The negotiable terms of the deal.
webPropertyCode

string

The web property code for the seller copied over from the product.
sellerContacts[]

object (ContactInformation)

Output only. Seller contact information for the deal.
availableStartTime

string (Timestamp format)

Optional. Proposed flight start time of the deal. This will generally be stored in the granularity of one second since deal serving starts at seconds boundary. Any time specified with more granularity (for example, in milliseconds) will be truncated towards the start of time in seconds.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
availableEndTime

string (Timestamp format)

Proposed flight end time of the deal. This will generally be stored in a granularity of a second. A value is not required for Private Auction deals or Preferred Deals.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
description

string

Description for the deal terms.
targetingCriterion[]

object (TargetingCriteria)

The shared targeting visible to buyers and sellers. Each shared targeting entity is AND'd together.
targeting

object (MarketplaceTargeting)

Output only. Specifies the subset of inventory targeted by the deal.
creativeRestrictions

object (CreativeRestrictions)

Output only. Restricitions about the creatives associated with the deal (for example, size) This is available for Programmatic Guaranteed/Preferred Deals in Ad Manager.
externalDealId

string

Output only. The external deal ID assigned to this deal once the deal is finalized. This is the deal ID that shows up in serving/reporting etc.
syndicationProduct

enum (SyndicationProduct)

The syndication product associated with the deal.

Note: This field may be set only when creating the resource. Modifying this field while updating the resource will result in an error.
creativePreApprovalPolicy

enum (CreativePreApprovalPolicy)

Output only. Specifies the creative pre-approval policy.
creativeSafeFrameCompatibility

enum (CreativeSafeFrameCompatibility)

Output only. Specifies whether the creative is safeFrame compatible.
dealServingMetadata

object (DealServingMetadata)

Output only. Metadata about the serving status of this deal.
programmaticCreativeSource

enum (ProgrammaticCreativeSource)

Output only. Specifies the creative source for programmatic deals. PUBLISHER means creative is provided by seller and ADVERTISER means creative is provided by buyer.
deliveryControl

object (DeliveryControl)

The set of fields around delivery control that are interesting for a buyer to see but are non-negotiable. These are set by the publisher.
isSetupComplete

boolean

Output only. True, if the buyside inventory setup is complete for this deal.

PrivateData

Buyers are allowed to store certain types of private data in a proposal/deal.

JSON representation 
{
  "referenceId": string
}
Fields
referenceId

string

A buyer or seller specified reference ID. This can be queried in the list operations (max-length: 1024 unicode code units).

MarketplaceTargeting

Targeting represents different criteria that can be used by advertisers to target ad inventory. For example, they can choose to target ad requests only if the user is in the US. Multiple types of targeting are always applied as a logical AND, unless noted otherwise.

JSON representation 
{
  "geoTargeting": {
    object (CriteriaTargeting)
  },
  "inventorySizeTargeting": {
    object (InventorySizeTargeting)
  },
  "technologyTargeting": {
    object (TechnologyTargeting)
  },
  "placementTargeting": {
    object (PlacementTargeting)
  },
  "videoTargeting": {
    object (VideoTargeting)
  }
}
Fields
geoTargeting

object (CriteriaTargeting)

Geo criteria IDs to be included/excluded.
inventorySizeTargeting

object (InventorySizeTargeting)

Inventory sizes to be included/excluded.
technologyTargeting

object (TechnologyTargeting)

Technology targeting information, for example, operating system, device category.
placementTargeting

object (PlacementTargeting)

Placement targeting information, for example, URL, mobile applications.
videoTargeting

object (VideoTargeting)

Video targeting information.

CriteriaTargeting

Generic targeting used for targeting dimensions that contains a list of included and excluded numeric IDs.

JSON representation 
{
  "targetedCriteriaIds": [
    string
  ],
  "excludedCriteriaIds": [
    string
  ]
}
Fields
targetedCriteriaIds[]

string (int64 format)

A list of numeric IDs to be included.
excludedCriteriaIds[]

string (int64 format)

A list of numeric IDs to be excluded.

InventorySizeTargeting

Represents the size of an ad unit that can be targeted on an ad request. It only applies to Private Auction, AdX Preferred Deals and Auction Packages. This targeting does not apply to Programmatic Guaranteed and Preferred Deals in Ad Manager.

JSON representation 
{
  "targetedInventorySizes": [
    {
      object (AdSize)
    }
  ],
  "excludedInventorySizes": [
    {
      object (AdSize)
    }
  ]
}
Fields
targetedInventorySizes[]

object (AdSize)

A list of inventory sizes to be included.
excludedInventorySizes[]

object (AdSize)

A list of inventory sizes to be excluded.

AdSize

Represents size of a single ad slot, or a creative.

JSON representation 
{
  "width": string,
  "height": string,
  "sizeType": enum (SizeType)
}
Fields
width

string (int64 format)

The width of the ad slot in pixels. This field will be present only when size type is PIXEL.
height

string (int64 format)

The height of the ad slot in pixels. This field will be present only when size type is PIXEL.
sizeType

enum (SizeType)

The size type of the ad slot.

SizeType

Represents different types of ad slot/creative sizing.

Enums
SIZE_TYPE_UNSPECIFIED A placeholder for an undefined size type.
PIXEL Ad slot with size specified by height and width in pixels.
INTERSTITIAL Special size to describe an interstitial ad slot.
NATIVE Native (mobile) ads rendered by the publisher.
FLUID Fluid size (for example, responsive size) can be resized automatically with the change of outside environment.

TechnologyTargeting

Represents targeting about various types of technology.

JSON representation 
{
  "deviceCategoryTargeting": {
    object (CriteriaTargeting)
  },
  "deviceCapabilityTargeting": {
    object (CriteriaTargeting)
  },
  "operatingSystemTargeting": {
    object (OperatingSystemTargeting)
  }
}
Fields
deviceCategoryTargeting

object (CriteriaTargeting)

IDs of device categories to be included/excluded.
deviceCapabilityTargeting

object (CriteriaTargeting)

IDs of device capabilities to be included/excluded.
operatingSystemTargeting

object (OperatingSystemTargeting)

Operating system related targeting information.

OperatingSystemTargeting

Represents targeting information for operating systems.

JSON representation 
{
  "operatingSystemCriteria": {
    object (CriteriaTargeting)
  },
  "operatingSystemVersionCriteria": {
    object (CriteriaTargeting)
  }
}
Fields
operatingSystemCriteria

object (CriteriaTargeting)

IDs of operating systems to be included/excluded.
operatingSystemVersionCriteria

object (CriteriaTargeting)

IDs of operating system versions to be included/excluded.

PlacementTargeting

Represents targeting about where the ads can appear, for example, certain sites or mobile applications. Different placement targeting types will be logically OR'ed.

JSON representation 
{
  "urlTargeting": {
    object (UrlTargeting)
  },
  "mobileApplicationTargeting": {
    object (MobileApplicationTargeting)
  }
}
Fields
urlTargeting

object (UrlTargeting)

URLs to be included/excluded.
mobileApplicationTargeting

object (MobileApplicationTargeting)

Mobile application targeting information in a deal. This doesn't apply to Auction Packages.

UrlTargeting

Represents a list of targeted and excluded URLs (for example, google.com). For Private Auction and AdX Preferred Deals, URLs are either included or excluded. For Programmatic Guaranteed and Preferred Deals, this doesn't apply.

JSON representation 
{
  "targetedUrls": [
    string
  ],
  "excludedUrls": [
    string
  ]
}
Fields
targetedUrls[]

string

A list of URLs to be included.
excludedUrls[]

string

A list of URLs to be excluded.

MobileApplicationTargeting

Mobile application targeting settings.

JSON representation 
{
  "firstPartyTargeting": {
    object (FirstPartyMobileApplicationTargeting)
  }
}
Fields
firstPartyTargeting

object (FirstPartyMobileApplicationTargeting)

Publisher owned apps to be targeted or excluded by the publisher to display the ads in.

FirstPartyMobileApplicationTargeting

Represents a list of targeted and excluded mobile application IDs that publishers own. Mobile application IDs are from App Store and Google Play Store. Android App ID, for example, com.google.android.apps.maps, can be found in Google Play Store URL. iOS App ID (which is a number) can be found at the end of iTunes store URL. First party mobile applications is either included or excluded.

JSON representation 
{
  "targetedAppIds": [
    string
  ],
  "excludedAppIds": [
    string
  ]
}
Fields
targetedAppIds[]

string

A list of application IDs to be included.
excludedAppIds[]

string

A list of application IDs to be excluded.

VideoTargeting

Represents targeting information about video.

JSON representation 
{
  "targetedPositionTypes": [
    enum (PositionType)
  ],
  "excludedPositionTypes": [
    enum (PositionType)
  ]
}
Fields
targetedPositionTypes[]

enum (PositionType)

A list of video positions to be included. When the included list is present, the excluded list must be empty. When the excluded list is present, the included list must be empty.
excludedPositionTypes[]

enum (PositionType)

A list of video positions to be excluded. Position types can either be included or excluded (XOR).

PositionType

Represents a targetable position within a video.

Enums
POSITION_TYPE_UNSPECIFIED A placeholder for an undefined video position.
PREROLL Ad is played before the video.
MIDROLL Ad is played during the video.
POSTROLL Ad is played after the video.

CreativeRestrictions

Represents creative restrictions associated to Programmatic Guaranteed/ Preferred Deal in Ad Manager. This doesn't apply to Private Auction and AdX Preferred Deals.

JSON representation 
{
  "creativeFormat": enum (CreativeFormat),
  "creativeSpecifications": [
    {
      object (CreativeSpecification)
    }
  ],
  "skippableAdType": enum (SkippableAdType)
}
Fields
creativeFormat

enum (CreativeFormat)

The format of the environment that the creatives will be displayed in.
creativeSpecifications[]

object (CreativeSpecification)
skippableAdType

enum (SkippableAdType)

Skippable video ads allow viewers to skip ads after 5 seconds.

CreativeFormat

Represents the format of a creative.

Enums
CREATIVE_FORMAT_UNSPECIFIED A placeholder for an undefined creative format.
DISPLAY A creative that will be displayed in environments such as a browser.
VIDEO A video creative that will be displayed in environments such as a video player.

CreativeSpecification

Represents information for a creative that is associated with a Programmatic Guaranteed/Preferred Deal in Ad Manager.

JSON representation 
{
  "creativeSize": {
    object (AdSize)
  },
  "creativeCompanionSizes": [
    {
      object (AdSize)
    }
  ]
}
Fields
creativeSize

object (AdSize)

The size of the creative.
creativeCompanionSizes[]

object (AdSize)

Companion sizes may be filled in only when this is a video creative.

SkippableAdType

The type of skippable ad for video creatives.

Enums
SKIPPABLE_AD_TYPE_UNSPECIFIED A placeholder for an undefined skippable ad type.
SKIPPABLE This video ad can be skipped after 5 seconds.
INSTREAM_SELECT This video ad can be skipped after 5 seconds, and is counted as engaged view after 30 seconds. The creative is hosted on YouTube only, and viewcount of the YouTube video increments after the engaged view.
NOT_SKIPPABLE This video ad is not skippable.

CreativePreApprovalPolicy

Specifies the creative pre-approval policy requirements.

Enums
CREATIVE_PRE_APPROVAL_POLICY_UNSPECIFIED A placeholder for an undefined creative pre-approval policy.
SELLER_PRE_APPROVAL_REQUIRED The seller needs to approve each creative before it can serve.
SELLER_PRE_APPROVAL_NOT_REQUIRED The seller does not need to approve each creative before it can serve.

CreativeSafeFrameCompatibility

Specifies whether the creative needs to be safe-frame compatible or not.

Enums
CREATIVE_SAFE_FRAME_COMPATIBILITY_UNSPECIFIED A placeholder for an undefined creative safe-frame compatibility.
COMPATIBLE The creatives need to be compatible with the safe frame option.
INCOMPATIBLE The creatives can be incompatible with the safe frame option.

DealServingMetadata

Message captures metadata about the serving status of a deal.

JSON representation 
{
  "dealPauseStatus": {
    object (DealPauseStatus)
  }
}
Fields
dealPauseStatus

object (DealPauseStatus)

Output only. Tracks which parties (if any) have paused a deal.

DealPauseStatus

Tracks which parties (if any) have paused a deal. The deal is considered paused if either hasBuyerPaused or hasSellPaused is true.

JSON representation 
{
  "hasBuyerPaused": boolean,
  "hasSellerPaused": boolean,
  "firstPausedBy": enum (BuyerSellerRole),
  "buyerPauseReason": string,
  "sellerPauseReason": string
}
Fields
hasBuyerPaused

boolean

True, if the buyer has paused the deal unilaterally.
hasSellerPaused

boolean

True, if the seller has paused the deal unilaterally.
firstPausedBy

enum (BuyerSellerRole)

The role of the person who first paused this deal.
buyerPauseReason

string

The buyer's reason for pausing, if the buyer paused the deal.
sellerPauseReason

string

The seller's reason for pausing, if the seller paused the deal.

BuyerSellerRole

Indicates which party performed a given operation.

Enums
BUYER_SELLER_ROLE_UNSPECIFIED A placeholder for an undefined buyer/seller role.
BUYER Specifies the role as buyer.
SELLER Specifies the role as seller.

ProgrammaticCreativeSource

Specifies the creative source for the programmatic deal.

Enums
PROGRAMMATIC_CREATIVE_SOURCE_UNSPECIFIED A placeholder for an undefined programmatic creative source.
ADVERTISER The advertiser provides the creatives.
PUBLISHER The publisher provides the creatives to be served.

DeliveryControl

Message contains details about how the deals will be paced.

JSON representation 
{
  "deliveryRateType": enum (DeliveryRateType),
  "frequencyCaps": [
    {
      object (FrequencyCap)
    }
  ],
  "creativeBlockingLevel": enum (CreativeBlockingLevel)
}
Fields
deliveryRateType

enum (DeliveryRateType)

Output only. Specifies how the impression delivery will be paced.
frequencyCaps[]

object (FrequencyCap)

Output only. Specifies any frequency caps.
creativeBlockingLevel

enum (CreativeBlockingLevel)

Output only. Specified the creative blocking levels to be applied.

DeliveryRateType

Specifies how the impression delivery will be paced.

Enums
DELIVERY_RATE_TYPE_UNSPECIFIED A placeholder for an undefined delivery rate type.
EVENLY Impressions are served uniformly over the life of the deal.
FRONT_LOADED Impressions are served front-loaded.
AS_FAST_AS_POSSIBLE Impressions are served as fast as possible.

FrequencyCap

Frequency cap.

JSON representation 
{
  "maxImpressions": integer,
  "numTimeUnits": integer,
  "timeUnitType": enum (TimeUnitType)
}
Fields
maxImpressions

integer

The maximum number of impressions that can be served to a user within the specified time period.
numTimeUnits

integer

The amount of time, in the units specified by timeUnitType. Defines the amount of time over which impressions per user are counted and capped.
timeUnitType

enum (TimeUnitType)

The time unit. Along with numTimeUnits defines the amount of time over which impressions per user are counted and capped.

TimeUnitType

Specifies the time-unit type for delivery control.

Enums
TIME_UNIT_TYPE_UNSPECIFIED A placeholder for an undefined time unit type. This just indicates the variable with this value hasn't been initialized.
MINUTE Minute
HOUR Hour
DAY Day
WEEK Week
MONTH Month
LIFETIME Lifetime
POD Pod
STREAM Stream

CreativeBlockingLevel

Indicates which of the creative blocking rules are applied to bids on this deal.

Enums
CREATIVE_BLOCKING_LEVEL_UNSPECIFIED A placeholder for an undefined creative blocking level.
PUBLISHER_BLOCKING_RULES Publisher blocking rules will be applied.
ADX_POLICY_BLOCKING_ONLY The Ad Exchange policy blocking rules will be applied.

ProposalState

The state of the proposal.

Enums
PROPOSAL_STATE_UNSPECIFIED A placeholder for an undefined proposal state.
PROPOSED The proposal is under negotiation or renegotiation.
BUYER_ACCEPTED The proposal has been accepted by the buyer.
SELLER_ACCEPTED The proposal has been accepted by the seller.
CANCELED The negotiations on the proposal were canceled and the proposal was never finalized.
FINALIZED The proposal is finalized. During renegotiation, the proposal may not be in this state.

Note

A proposal may be associated to several notes.

JSON representation 
{
  "proposalRevision": string,
  "noteId": string,
  "createTime": string,
  "creatorRole": enum (BuyerSellerRole),
  "note": string
}
Fields
proposalRevision

string (int64 format)

Output only. The revision number of the proposal when the note is created.
noteId

string

Output only. The unique ID for the note.
createTime

string (Timestamp format)

Output only. The timestamp for when this note was created.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
creatorRole

enum (BuyerSellerRole)

Output only. The role of the person (buyer/seller) creating the note.
note

string

The actual note to attach. (max-length: 1024 unicode code units)

Note: This field may be set only when creating the resource. Modifying this field while updating the resource will result in an error.

Methods

accept

 Mark the proposal as accepted at the given revision number.

addNote

 Create a new note and attach it to the proposal.

cancelNegotiation

 Cancel an ongoing negotiation on a proposal.

completeSetup

 Update the given proposal to indicate that setup has been completed.

create

 Create the given proposal.

get

 Gets a proposal given its ID.

list

 List proposals.

pause

 Update the given proposal to pause serving.

resume

 Update the given proposal to resume serving.

update

 Update the given proposal at the client known revision number.