User ID Sync Parameter

The user_id_sync parameter allows you to provide third-party identity IDs directly within an AdButler ad request.

This is useful when your application already has access to user identifiers from advertising partners, but cannot rely on browser-based cookie syncing. Common examples include server-to-server integrations, mobile applications, connected TV (CTV) applications, and other environments where cookies may not be available.

When supplied, IDs provided through user_id_sync take priority over any matching IDs that may already exist through AdButler's cookie synchronization mechanisms.

Supported Formats

Query String

You can provide one or more user IDs using bracket notation:

user_id_sync[magnite]=12345&user_id_sync[xandr]=67890

JSON Request Body

{
  "user_id_sync": {
    "magnite": "12345",
    "xandr": "67890"
  }
}

Legacy Matrix Parameter Format

For integrations using AdButler's semicolon-delimited request format:

;user_id_sync[magnite]=12345;user_id_sync[xandr]=67890

Supported Identity Providers

The following sync types are currently supported:

Example

{
  "user_id_sync": {
    "magnite": "abc123xyz",
    "xandr": "987654321"
  }
}

In this example, AdButler will associate the request with the supplied Magnite and Xandr user IDs and make them available for supported demand partners and integrations.

Validation Rules

Each user ID is validated independently.

• Empty values are ignored.
• Unknown sync types are ignored.
• Multiple sync types can be supplied in a single request.
• Valid sync types are processed even if other supplied types are invalid.

For example:

{
  "user_id_sync": {
    "magnite": "abc123",
    "unknown_partner": "xyz789"
  }
}

In this case, the Magnite ID will be accepted and the unknown partner will be ignored.

Priority and Overrides

If AdButler already has a stored user ID for a supported partner, and the same partner ID is supplied through user_id_sync, the value provided in the request will be used.

Example:

{
  "user_id_sync": {
    "magnite": "new-id-123"
  }
}

If a Magnite ID was previously available through cookie synchronization, new-id-123 will override it for the current request.

Common Use Cases

Connected TV (CTV)

CTV applications often cannot participate in traditional browser cookie syncing. Supplying partner IDs directly allows identity matching to continue working in these environments.

Mobile Applications

Mobile SDKs or applications may maintain partner identifiers independently and can pass them directly to AdButler.

Server-to-Server Integrations

When an upstream platform already possesses partner identity mappings, those IDs can be forwarded to AdButler without requiring browser synchronization.

Related Parameters

AdButler also supports dedicated parameters for certain identity use cases:

Unlike these dedicated parameters, user_id_sync allows multiple identity providers to be supplied in a single request.