Mutation examples for gRPC real-time data integrations

Real-time mutations are sell-side decisioning inputs that enrich and inform Index Exchange (Index) auctions made in the milliseconds leading up to bid submission. Examples include:

• Activate or suppress deals

• Adjust the floor price of an active deal

• Activate user segments

• Add approved extended content IDs

Mutations are atomic, where if a mutation fails validation or execution, no changes are applied for that mutation.

General conditions

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

• Each mutation applies to a single, explicitly referenced impression opportunity.

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

Activate a deal

Activate a deal for a specific impression opportunity.

This mutation enables impression-level deal activation by allowing a deal to be activated only when an impression meets specific criteria. Deals can be selectively activated for high-value or strategic impression opportunities (for example, based on user context, content signals, or demand conditions), ensuring preferred buyers are exposed only to impressions that align with campaign goals and maximizing the effectiveness of deal delivery.

Conditions

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

Example

Activate deal deal123 for impression opportunity imp123:

{ 
	intent: ACTIVATE_DEALS, 
	path: "/imp/imp123", 
	op: OPERATION_ADD, 
	value: IDsPayload.ids("deal123") 
} 

Suppress a deal

Prevent a deal from activating for a specific impression opportunity.

This mutation enables impression-level control over deal eligibility by preventing a deal from activating for specific impression opportunities. Deals can be suppressed when an impression does not meet desired criteria (for example, based on user context, content signals, or business rules), allowing publishers to avoid exposing low-value or non-ideal impressions to certain buyers and preserve deal performance for higher-quality opportunities.

Conditions

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

Example

Suppress deal deal123 for impression imp123:

{ 
	intent: SUPPRESS_DEALS, 
	path: "/imp/imp123", 
	op: OPERATION_REMOVE, 
	value: IDsPayload.ids("deal123") 
} 

Adjust deal floor

Modify the floor price of an activated deal, before the bid request is sent to the DSP, for a specific impression opportunity.

This mutation enables dynamic value optimization at impression time, allowing the deal floor to be adjusted based on the expected value of an individual impression. For higher-value impressions (for example, based on user context, content signals, or demand conditions), the floor can be increased. For lower-value impressions, the floor can be reduced to improve cost efficiency while still maintaining competitiveness based on impression-level signals. This can also support pacing strategies by adjusting win rates as delivery or budget goals change.

Conditions

• The floor price must be between 0.01 and 655.35.

• Programmatic Guaranteed deal floors can't 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 will continue using the publisher's signaled floor.

Example

Set the floor of deal deal123 to $5.00 for impression imp123:

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

Activate segments

Activate user segments required for deal activation for a specific impression opportunity.

This mutation 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 the deal activation mutation when more explicit and predictable control is required.

Conditions

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

Example

Activate segments segment111 and segment222 using separate mutations:

{ 
	intent: ACTIVATE_SEGMENTS, 
	path: "/user/data", 
	op: OPERATION_ADD, 
	value: IDsPayload.ids("segment111") 
}, 
{ 
	intent: ACTIVATE_SEGMENTS, 
	path: "/user/data", 
	op: OPERATION_ADD, 
	value: IDsPayload.ids("segment222") 
} 

Add Extended Content IDs

Pass approved Extended Content IDs in the real-time data request for a specific impression opportunity.

This mutation 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 make changes to their existing integrations.

Conditions

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.

Example

Add Extended Content IDs:

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