Cached API integration method

This method requires that you integrate with Index Exchange (Index) by registering your segment taxonomy on our platform and connecting to Index using an HTTP GET endpoint A URL which is configured to interact with a server in a specific way.. After the integration is complete, Index begins storing your responses in a cached location. When Index receives an ad request, we check the cached data against specific OpenRTB An open industry standard for communication between buyers and sellers of online advertising in real-time bidding auctions. It's published by the IAB. attributes sent in the incoming request (for example, page URL or app bundle ID). If we find segments that match the attributes before a specified timeout, they are added to the request, any matching deals are activated, and the request is sent to DSPs. If we don't find any relevant segments, Index makes an asynchronous call to your endpoint with OpenRTB attributes in the request. If we receive a response with updated segment data before a specified timeout, we write the updated data to the cache so it can be used in a future request.

Supported enrichment keys

Index supports enrichment against the following OpenRTB attributes. Each key corresponds to a macro you configure in your endpoint URL (see Request formats). Keys fall into two categories:

• Single keys: Index makes one call per key, populating only that value in the URL.

• Complex keys: Two attributes are always enriched together as a combined cache key. Both macros must be present in your endpoint; Index will not call the endpoint unless values for both fields are available.

Note: The Multi-field Contextual Key is a special composite key that bundles multiple fields into prescribed query string parameters (app/pageUrl, device, mediaType, size) in a single URL substitution. For example: appId=my-app-bundle&device=1&mediaType=display&size=5x5. It behaves as a single-call key.

How complex keys work

For complex key pairs, both macros must appear in your endpoint URL. Index will only make a call when both field values are present in 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., and the response is cached against the combined key. This means:

• If either field is absent from the incoming bid request, no call is made and no cache lookup is attempted for that pair.

• The cached response is keyed against the combination of both values, so the same page URL paired with a different content ID is treated as a distinct cache entry.

Complex key pairs explained

Page URL + Content ID ({SITE_PAGE_COMPLEX_MACRO} + {CONTENT_ID_COMPLEX_MACRO})

Use this when page URL alone isn't specific enough, for example, a news homepage that hosts many different articles. Pairing the URL with a content ID lets your model differentiate segments at the article level rather than the domain level.

App Bundle + Content ID ({APP_BUNDLE_COMPLEX_MACRO} + {CONTENT_ID_COMPLEX_MACRO})

This is the in-app equivalent of the above. App bundle identifies the application, but many apps surface varied content (for example, a sports app with separate feeds per league or team). Adding content ID allows enrichment at that finer granularity.

Country + ZIP/ Postal Code ({DEVICE_COUNTRY_MACRO} + {DEVICE_ZIP_MACRO})

ZIP and postal codes are not globally unique, as the same code can exist in multiple countries. Country must always accompany the ZIP or postal code to produce an unambiguous geographic key. Index will not enrich against a ZIP or postal code alone for this reason. The country code must be an ISO 3-character country code.

For example, consider a partner configured for Page URL + Content ID with the endpoint https://partner.com/enrich?url={SITE_PAGE_COMPLEX_MACRO}&cid={CONTENT_ID_COMPLEX_MACRO}. With a bid request containing site.page = https://sports.com/soccer and site.content.id = 123456789, Index makes a single call: GET https://partner.com/enrich?url=https%3A%2F%2Fsports.com%2Fsoccer&cid=123456789

Request formats

Partners using a Cached API integration must expose an endpoint accessible through an HTTP GET request, where Index can embed the keys to enrich against (for example, URL, app bundle, or IP) in the URL as URL-encoded query string parameters.

Index populates the URL with one cache key per request, either a single key or a complex pair populated together. Index can also include additional keys in the request if they are useful to your decisioning logic, but the response is always cached against the primary cache key.

Example

Using an example endpoint of https://www.mypartner.com/segments?url={URL_MACRO}, if an incoming ad request includes the apple.com/developer/news/iphone URL, Index makes the following call to your endpoint: GET https://www.mypartner.com/segments?url=apple.com%2Fdeveloper%2Fnews%2Fiphone

Response format

The HTTP response should be in JSON format using the following structure:

Example:

{
	"segment_ids": ["cat_owners", "target_shoppers", "gender_female"]
}

Response codes and circuit breaker logic

The following HTTP response code rules and logic apply:

• A 2xx HTTP response code should be returned for successful responses from all partners.

• For cached Data Partners, if Index receives a 5xx error, Index does not cache any data and the request is eventually retried. If Index receives a 4xx error, Index caches information indicating that the request should not be retried, and no enrichment data from the partner is available for the given key.

Circuit breaker logic

If Index receives a 4xx or 5xx error, the internal circuit breaker logic is triggered, and requests to the affected partner's API are throttled. Requests to a partner's API that time out also trigger this same circuit breaker logic. Circuit breaker logic exists to protect both Index and our partners' systems. When error rates return to nominal levels, circuit breakers reopen and regular traffic volume resumes.

Cached API response headers

Index honors the following HTTP response header for Cached API integrations.

Response examples

In the following example, Index requests data from a Data Partner's endpoint. The partner returns preliminary enrichment data and wants Index to continue to check back with their endpoint for the complete enrichment data.

HTTP/1.1 200 OK
Cache-Control: no-cache

{
	"segment_ids": ["sports_news", "football_players"]
}

In the following example, Index requests data from a partner's endpoint. The partner does not have any data available yet and wants Index to continue to check back.

HTTP/1.1 200 OK
Cache-Control: no-cache

{
	"segment_ids": []
}

Note: An empty response body is also acceptable in this situation.

In the following example, Index requests data from a partner's endpoint. The partner returns a full classification that should be cached for 24 hours (86,400 seconds).

HTTP/1.1 200 OK
Cache-Control: max-age=86400
{
	"segment_ids": ["sports_news", "football_players", "arsenal", "english_sports", "fa_cup"]
}

Authentication

If you require authentication, Index supports OAuth, as well as tokens in the query string.