REST Resource: accounts.proposals

Resource: Proposal

Note: this resource requires whitelisting for access. Please contact your account manager for access to Marketplace resources.

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 not update, create, or otherwise modify Private Auction or Preferred Deals 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)
    }
  ],
}
Fields
proposalId

string

The unique ID of the proposal.

Note: This field is used in responses only. Any value specified here in a request is ignored.

updateTime

string (Timestamp format)

The time when the proposal was last revised.

A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example: "2014-10-02T15:01:23.045123456Z".

Note: This field is used in responses only. Any value specified here in a request is ignored.

proposalRevision

string (int64 format)

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.

Note: This field is used in responses only. Any value specified here in a request is ignored.

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)

Indicates whether the buyer/seller created the proposal.

Note: This field is used in responses only. Any value specified here in a request is ignored.

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)

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

Note: This field is used in responses only. Any value specified here in a request is ignored.

displayName

string

The name for the proposal.

proposalState

enum(ProposalState)

The current state of the proposal.

Note: This field is used in responses only. Any value specified here in a request is ignored.

isRenegotiating

boolean

True if the proposal is being renegotiated.

Note: This field is used in responses only. Any value specified here in a request is ignored.

buyerPrivateData

object(PrivateData)

Private data for buyer. (hidden from seller).

sellerContacts[]

object(ContactInformation)

Contact information for the seller.

Note: This field is used in responses only. Any value specified here in a request is ignored.

buyerContacts[]

object(ContactInformation)

Contact information for the buyer.

privateAuctionId

string

Private auction ID if this proposal is a private auction proposal.

Note: This field is used in responses only. Any value specified here in a request is ignored.

isSetupComplete
(deprecated)

boolean

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

Note: This field is used in responses only. Any value specified here in a request is ignored.

lastUpdaterOrCommentorRole

enum(BuyerSellerRole)

The role of the last user that either updated the proposal or left a comment.

Note: This field is used in responses only. Any value specified here in a request is ignored.

notes[]

object(Note)

The notes associated with this proposal.

Note: This field is used in responses only. Any value specified here in a request is ignored.

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)
    }
  ],
  "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

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

Note: This field is used in responses only. Any value specified here in a request is ignored.

proposalId

string

ID of the proposal that this deal is part of.

Note: This field is used in responses only. Any value specified here in a request is ignored.

createTime

string (Timestamp format)

The time of the deal creation.

A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example: "2014-10-02T15:01:23.045123456Z".

Note: This field is used in responses only. Any value specified here in a request is ignored.

updateTime

string (Timestamp format)

The time when the deal was last updated.

A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example: "2014-10-02T15:01:23.045123456Z".

Note: This field is used in responses only. Any value specified here in a request is ignored.

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 sinced 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)

Seller contact information for the deal.

Note: This field is used in responses only. Any value specified here in a request is ignored.

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 (e.g., in milliseconds) will be truncated towards the start of time in seconds.

A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example: "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, accurate to nanoseconds. Example: "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.

externalDealId

string

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.

Note: This field is used in responses only. Any value specified here in a request is ignored.

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)

Specifies the creative pre-approval policy.

Note: This field is used in responses only. Any value specified here in a request is ignored.

creativeSafeFrameCompatibility

enum(CreativeSafeFrameCompatibility)

Specifies whether the creative is safeFrame compatible.

Note: This field is used in responses only. Any value specified here in a request is ignored.

dealServingMetadata

object(DealServingMetadata)

Metadata about the serving status of this deal.

Note: This field is used in responses only. Any value specified here in a request is ignored.

programmaticCreativeSource

enum(ProgrammaticCreativeSource)

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

Note: This field is used in responses only. Any value specified here in a request is ignored.

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

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

Note: This field is used in responses only. Any value specified here in a request is ignored.

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

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)

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

Note: This field is used in responses only. Any value specified here in a request is ignored.

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)

Specifies how the impression delivery will be paced.

Note: This field is used in responses only. Any value specified here in a request is ignored.

frequencyCaps[]

object(FrequencyCap)

Specifies any frequency caps.

Note: This field is used in responses only. Any value specified here in a request is ignored.

creativeBlockingLevel

enum(CreativeBlockingLevel)

Specified the creative blocking levels to be applied.

Note: This field is used in responses only. Any value specified here in a request is ignored.

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": number,
  "numTimeUnits": number,
  "timeUnitType": enum(TimeUnitType),
}
Fields
maxImpressions

number

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

numTimeUnits

number

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

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)

The revision number of the proposal when the note is created.

Note: This field is used in responses only. Any value specified here in a request is ignored.

noteId

string

The unique ID for the note.

Note: This field is used in responses only. Any value specified here in a request is ignored.

createTime

string (Timestamp format)

The timestamp for when this note was created.

A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example: "2014-10-02T15:01:23.045123456Z".

Note: This field is used in responses only. Any value specified here in a request is ignored.

creatorRole

enum(BuyerSellerRole)

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

Note: This field is used in responses only. Any value specified here in a request is ignored.

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.

Send feedback about...

Buyer REST API
Buyer REST API