You are here: Publishers > Basics > About Key-Value Pairs

About key value pairs

A key-value pair is a set of two linked data items: a key, which is a unique identifier for some item of data, and the value, which is either the data that is identified or a pointer to the location of that data. For example: "firstname" : "John". JSON data is written as key-value pairs.

The OpenX UI and API both use key-value pairs and the following sections describe where they are used.

Note: In OpenX, key-value pairs are also referred to as "custom values", "custom variables", "custom key-values", or "custom key-value pairs".

Pre-defined or custom key-value pairs

Key value pairs in OpenX can be pre-defined or custom (user-defined):


For some objects, such as a function, method, or REST call, key-value pairs will already be pre-defined for you. When this is the case, you will use the pre-defined "keys" and enter appropriate "values" to produce the results you want.


In other cases, you will be allowed to create your own "custom" key-value pairs. This allows you to extend an existing function to gather or provide additional custom information.


Note that, for some areas, such as the Key Value Report, you must whitelistMarking a particular entity as “approved” in order to ensure it is included. A whitelist will block new entities by default whereas a blacklist will allow new entities by default. For example, you could use a whitelist to only allow the "Technology" industry. the key-value pairs that you want to appear on the report. For information, see your account manager.

General characteristics of key value pairs

Keys should be:

  • lowercase

  • alphanumeric

  • underscores are allowed

Keys should not:

  • begin with a number

  • be case-sensitive

Key value pairs in OpenX


For publishers, the following table contains a brief explanation of how key-value pairs are used in each area of the OpenX application and links to corresponding topics.

Application Area Description and Links

You can include custom variables to provide additional information about your ad space if available ad requestCommunication between a web browser or application and an ad server to display an ad. parameters do not meet your needs. For more information, see Custom variables for targeting.

MacrosFor OpenX, a command enclosed in curly braces {} that dynamically inserts attributes into your HTML or third-party ad creatives and click-through URLs when OpenX serves an ad. Other macros, like from your video player, may have alternate formatting.

For publishers, you can use where "xxx" is replaced with the value for any custom key-value pair enrichment variable. For example, if you have a custom variable for users' names or hobbies (e.g., or c.hobby=) and you then inserted the {} or {c.hobby} macros, OpenX would replace the macros with the values of the custom variables. For example: or c.hobby. For more information, see Supported macros: key-value pair macro.

Event-level feeds

Event-level feeds provides a "custom_fields" variable which is a caret-delimited list of custom variables for an event. These are passed as key-value pairs in the call, using the format: c.<key>=<value>. For example: c.gender=male or c.age=30. Note: OpenX populates custom_fields values if they are whitelisted. Please contact your OpenX account manager for details on how to whitelist custom_fields. For more information, see What data does OpenX make available for each event?.

Custom key-value report

OpenX provides a custom key-value report that allows you to view inventoryAd space available on a website or app. The basic unit of inventory for OpenX is an ad unit. performance per custom key and key value for both Ad ServerA complete digital advertising platform where publishers sell, manage, and deliver their advertising inventory across all digital formats. direct revenue and Exchange revenue. (Custom key-value reporting is not available for SSPSupply-side platform, a platform or provider that allows publishers to manage and optimize revenue for their inventory from multiple sources, often in real time. network data.)

Ad Request API

In the Ad Request API, if available Ad request parameters do not meet your needs, you can include custom variables to provide additional information about your ad space. See Custom variables in ad requests.

You can also use custom key-value pairs (KVPs) to provide additional information about your ad space. See the "vars" parameter in Asynchronous JavaScript ad tags.

For mobile ad requests, you can use a custom variable (c.keyvalue=) that communicates additional information about the ad space, such as details of webpage content, ad space location, or user-specific information. For example: c.gender=1. For details, see custom variables in ad requests. See Mobile ad request parameters.

One of the OX static methods (addVariable) allows you to specify a key-value pair to add to all ad requests for the current page view. Also, see the "vars" parameter in the requestAd static method.

One of the OX instance methods (addVariable) allows you to specify a key-value pair to add to all ad requests for the ad tagA small piece of code that defines the ad space where ads display on a website. It includes parameters that describe the inventory advertising campaigns can target, which may in turn display ads in the ad space.. See custom key-value report.

Demand Partners

Demand partners who are doing real-time bidding can reference key value pairs. The following table contains a brief explanation of how demand partners can use key-value pairs and links to corresponding topics.

Application Area Description and Links

The OpenRTB API provides a BidRequest extension (tp_key_val) that contains a list of third-party key-value pairs:


Third-party key-values

BidRequest object

You can express mobile ad request parameters as key-value pairs. See step 3 in the following link: OpenRTB mobile app use case

OpenX proprietary API

The OpenX Proprietary API allows you to use key-value pairs to describe a user who is viewing an impressionA single display of an ad on a web page, mobile app, or other delivery medium. See also billable impression, forecasted impressions.. For more information, see User object.

Feedback form