Mutation reference

Before you begin: Complete Build a gRPC RTD service. Mutations are the outputs your GetMutations handler returns.

Note: This reference applies whether your container is hosted in Index Cloud or on your own infrastructure (partner-hosted). The fields and privacy rules described here are the same for both deployment models.

Real-time mutations are sell-side decisioning inputs that enrich and inform Index Exchange (Index) auctions in the milliseconds leading up to bid submission. All mutations share the same structure: intent, path, op, and value, shown in protojson format. Mutations are atomic: if a mutation fails validation or execution, no changes are applied for that mutation.

General conditions

The following conditions apply to all mutations:

• Not all mutations fire at the same point in the auction lifecycle. ACTIVATE_DEALS, SUPPRESS_DEALS, ADJUST_DEAL_FLOOR, ACTIVATE_SEGMENTS, and ADD_CIDS fire at the Publisher The owner of a website or app where advertisements are served. Request extension point, before bids go to DSPs. BID_SHADE fires at the DSP Demand-Side Platform (DSP). A software platform that automates bidding decisions in real-time and efficiently connects buyers and audiences through an ad exchange or SSP. Also known as a buy-side platform. Bid Response An OpenRTB response that is sent by the DSP in response to the SSP's or ad exchange's bid request. It is an event directed back to the seller expressing a valuation for the request and conditions of sale. extension point, after DSPs have responded. Your GetMutations handler receives a lifecycle field on every call; route your logic accordingly and only return mutations valid for that extension point.

• Mutations can only be applied to deals and entities that the partner owns or has been granted permission to modify.

• Each mutation applies to a single, explicitly referenced entity: an impression opportunity for deal A private auction that allows media owners to offer specific inventory directly to selected buyers identified by a deal ID. Terms are negotiated and are agreed upon before the auction occurs.- and bid-related mutations, or the user or content object for ACTIVATE_SEGMENTS and ADD_CIDS.

• Only one entity, for example a deal ID or segment ID, is supported per mutation unless otherwise noted.

• If a mutation fails, no partial changes are applied.

• Mutations are treated as requests and may be rejected by Index based on validation, eligibility, or platform enforcement rules.

• All examples are shown in protojson format, a standardized JSON representation of protobuf payloads.

Activate a deal

Activate a deal for a specific impression opportunity. This enables impression-level deal activation: deals can be selectively activated for high-value or strategic impression opportunities based on user context, content signals, or demand conditions, ensuring preferred buyers are exposed only to impressions that align with campaign A collection of multiple ads in different formats. goals.

Note: The deal must already be eligible to transact: active, within start and end dates, and properly configured in Index.

The following example activates deal deal123 for impression imp123:

{
   "intent": "ACTIVATE_DEALS",
   "op": "OPERATION_ADD",
   "path": "/imp/imp123",
   "ids": { "id": ["deal123"] }
}

Suppress a deal

Prevent a deal from activating for a specific impression opportunity. Deals can be suppressed when an impression does not meet desired criteria, allowing publishers to avoid exposing low-value or non-ideal impressions to certain buyers and preserve deal performance for higher-quality opportunities.

Note: The deal must already be eligible to transact: active, within start and end dates, and properly configured in Index.

The following example suppresses deal deal123 for impression imp123:

{
   "intent": "SUPPRESS_DEALS",
   "op": "OPERATION_REMOVE",
   "path": "/imp/imp123",
   "ids": { "id": ["deal123"] }
}

Adjust deal floor

Modify the floor A pricing control used by media owners and exchanges to set a minimum sale price on inventory. price of an activated deal before the bid request An OpenRTB request that is sent from a supply-side platform (SSP) or ad exchange to the DSP requesting a bid response for potential impressions. A bid request contains information about the impression that allows the DSP to decide whether to bid on the impression. is sent to the DSP. This enables dynamic value optimization at impression time: floors can be raised for high-value impressions to maximize yield, or lowered for lower-value impressions to improve cost efficiency while maintaining competitiveness.

Note: The following conditions apply:

• The floor price must be between 0.01 and 655.35.

• Programmatic Guaranteed deal floors cannot be adjusted.

• If multiple adjustments target the same deal, the last mutation wins.

• If the suggested floor is lower than the publisher's floor in the inbound ad request, Index continues using the publisher's signaled floor.

The following example sets the floor of deal deal123 to $5.00 for impression imp123:

{
   "intent": "ADJUST_DEAL_FLOOR",
   "op": "OPERATION_REPLACE",
   "path": "/imp/imp123/deal/deal123",
   "adjustDeal": { "bidfloor": 5.00 }
}

Activate segments

Activate user segments required for deal activation for a specific impression opportunity. This allows required user segments to be activated in real time so that eligible deals can activate for a given impression. Partners may prefer to activate deals directly using ACTIVATE_DEALS when more explicit and predictable control is required.

Note: Segment activation may have no effect if the segment is already activated through another workflow.

The following example activates segments segment111 and segment222 using separate mutations:

{
   "intent": "ACTIVATE_SEGMENTS", "op": "OPERATION_ADD",
   "path": "/user/data/segment", "ids": { "id": ["segment111"] }
},
{
   "intent": "ACTIVATE_SEGMENTS", "op": "OPERATION_ADD",
   "path": "/user/data/segment", "ids": { "id": ["segment222"] }
}

Add Extended Content IDs

Pass approved Extended Content IDs in the real-time data integration request for a specific impression opportunity. This allows approved content information to be added to an impression in real time, giving buyers more context to make better bidding decisions without requiring publishers to change their existing integrations.

Note: Content data names must be allowlisted with Index before they can be added. Contact your Index representative to request that additional content data names be added to the allowlist.

The following example adds two Extended Content IDs to the site content object:

{
   "intent": "ADD_CIDS",
   "op": "OPERATION_ADD",
   "path": "/site/content/data",
   "contentData": {
      "data": [{ "name": "example-container", "ext": { "cids": ["EX0000000000", "EZ0000000000"] } }]
   }
}

Shade a bid

Recommend a lower transaction price for a specific DSP bid, before Index selects a winner. The DSP pays the shaded price. This applies to first-price auctions only. Your container evaluates each DSP bid using your models and historical clearing prices, and returns a lower recommended price, reducing buyer cost without reducing win rates.

Note: For the business rules governing bid shading (price constraints, floor behavior, deal ownership), the handler implementation pattern, and the testing checklist, see Implementing bid shading.

The following example shades bid 456 on seat 123 to $1.85:

{
   "intent": "BID_SHADE",
   "op": "OPERATION_REPLACE",
   "path": "/seatbid/123/bid/456",
   "adjustBid": { "price": 1.85 }
}