As a Data Partner, you can integrate with the Index Exchange platform to make data available to publishers or Marketplace Partners The owner of an Index Marketplace that curates their media solutions within the Index Marketplace and packages these offerings to bring incremental demand to publishers. For example, a Marketplace partner could be a media agency, a data provider, or retail media network. when creating deals. You have the following options when determining how you want to integrate and activate data:
-
Using a File Upload integration: This option works well for Data Partners who do not have infrastructure that Index can call per request or have somewhat static item lists that represent their segments.
-
Using a Cached API integration: This option works well for Data Partners who activate their segment taxonomy using one to two fields, cannot respond within a small time-out limit, or want to limit how often Index calls them. For example, an API that returns contextual segments associated with a URL.
-
Using a Real Time Data (RTD) integration: This option works well for Data Partners that have a larger amount of data, who activate their segment taxonomy on multiple keys, can respond within low latency time limits, and can ideally be co-located with an Index data center. For example, segment activation on multiple fields in the request, or to keep matching logic proprietary. This is the recommended integration method.
File Upload integration method
This method requires that you share your segment files with Index in one of the following ways:
-
If your segment files include a grouping of people-based IDs, IP addresses, URLs, or other supported match keys, you can send your segment files to Index using SFTP to be processed within 15-20 minutes by the Audience Manager system. For more information about how this works, see Sending segment files to Index using SFTP.
-
If you want to match on main domain only, you can work with your Index Representative to upload these segment files using an API.
After Index has registered these values, these segments can be permissioned to accounts and targeted in deals. A deal A private auction that allows publishers to offer specific inventory directly to selected buyers identified by a deal ID. Terms are negotiated and are agreed upon before the auction occurs. activates and is sent to DSPs when Index receives ad requests that contain attributes that match a targeted segment’s match key value.
Cached API integration method
This method requires that you integrate with Index by registering your segment taxonomy on our platform and you connect 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, appbundle ID). If we find segments that match the attributes before a specified timeout, they are added to the request and any matching deals get activated and are then 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.
For more information about the integration requirements, see How to integrate Cached API and Real Time Data solutions with Index below.
Real-Time Data integration method
This method requires that you integrate with Index by registering your segment taxonomy on our platform and that you connect to Index using an HTTP POST endpoint. When Index receives an ad request, we make a call to your endpoint in real time with OpenRTB attributes, respecting user privacy choices and laws, and your endpoint responds with the relevant segment IDs or other meta-data to enrich the auction. The segment IDs are made available to be matched against Deal IDs with DSPs.
For more information about the integration requirements, see How to integrate Cached API and Real Time Data solutions with Index below.
How to integrate Cached API and Real Time Data solutions with Index
To be able to share your data with the Index platform using a Cached API or Real-Time Data integration, you need to set up an HTTP endpoint with Index Exchange.
Request formats
Cached API integrations
Partners using a Cached API integration must expose a endpoint accessible through an HTTP GET request, where Index can embed the keys to enrich against (for example, URL, app bundle, IP, etc) in the URL as URL-encoded query string parameters.
Index will only ever populate one key in the URL in an HTTP request to avoid needing to account for complex-cache keys. For partners providing enrichment against multiple keys, considerations for complex keys can be discussed. Index can also provide additional keys in the HTTP request if useful in decisioning logic, but the cache will be stored against the primary 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 would make the following call to your endpoint:
GET https://www.mypartner.com/segments?url=apple.com%2Fdeveloper%2Fnews%2FiphoneReal-Time Data integrations
Partners using a Real-Time Data integration must expose an endpoint accessible through an HTTP POST request, where Index will use the following OpenRTB attributes wherever possible for easy compatibility:
| Object | Description |
|---|---|
app
|
The app object is included if the impression originates from an application. It contains details about the publisher The owner of a website or app where advertisements are served.’s app (for example., a non-browser application). |
device
|
The device object that contains information about the user’s device to which the impression will be delivered. |
imp
|
The imp object that contains information about an ad placement or impression opportunity being auctioned, excluding the bidFloor field and the pmp Private Marketplace (PMP). An invitation-only real-time bidding auctions where one or several publishers invite a select number of advertisers to buy their inventory. object. It includes the GPID extension. |
site
|
The site object that contains details about the publisher’s website. It is included only if the impression originates from a website. |
user
|
The user object that contains details about the user of the device; the advertising audience. Index sends the user.id and and user.ext.eids objects when permitted by relevant third parties and privacy requirements are met. |
Any ext extension objects in the OpenRTB objects listed above are not sent unless explicitly stated. Some 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. attributes will be removed or modified due to privacy requirements (for example, IP addresses will be truncated as necessary, etc.) before they are sent to you. For more information about these OpenRTB attributes, see List of supported OpenRTB bid request fields for sellers.
Sample app request
{
"app": {
"id": "12345",
"name": "App Name",
"bundle": "123456789",
"domain": "appexample.com",
"storeurl": "https://apps.apps.com/app/idexample",
"cat": ["IAB9-7"],
"ver": "4.56.0",
"publisher": {
"id": "555555",
"name": "Publisher Name",
"domain": "appexample.com"
}
},
"device": {
"connectiontype": 2,
"devicetype": 4,
"dnt": 0,
"geo": {
"city": "Cityville",
"country": "USA",
"ipservice": 4,
"lat": 11.11,
"lon": -11.11,
"metro": "111",
"region": "NY",
"type": 2,
"utcoffset": -240,
"zip": "99999"
},
"ifa": "aaaaaaaa-ebad-aaaa-aaaa-aaaaaaa",
"ip": "123.45.6.789",
"language": "en",
"lmt": 0,
"make": "Phonester",
"model": "Phone",
"os": "Android",
"osv": "9",
"pxratio": 2,
"ua": "PhonesterPhone/1.0 (UnicornOS 3.7; UAX64) FizzleEngine/9.4 Mobile FlibberNet/5.6"
},
"imp": [
{
"banner": {
"w": 728,
"h": 90,
"pos": 1,
"topframe": 0
},
"secure": 1,
"ext": {
"gpid": "/1234567/home/mpu/atf"
},
"id": "1",
"tagid": "12345_12345"
}
],
"user": {
"id": "AbcdEfgHijklmnoP",
"ext": {
"eids": [
{
"source": "ID_Provider.com",
"uids": [
{
"id": "Abcdefgh1234567Abcdefgh1234567Abcdefgh1234567Abcdefgh1234567Abcdefgh1234567"
}
]
},
{
"source": "Provider_id.org",
"uids": [
{
"id": "123456-abcde-123456-abcde-123456"
}
]
}
]
}
},
"regs": {
"coppa": 0,
"ext": {
"gdpr": 0,
"us_privacy": "1---"
}
}
} Sample web request
{
{
"site": {
"id": "12345",
"page": "https://example.com/section/",
"domain": "example.com",
"ref": "https://exampleref.com/",
"publisher": {
"id": "555555",
"domain": "example.com",
"name": "Publisher Name"
},
"content": {
"url": "https://example.com/content-link/"
}
},
"device": {
"connectiontype": 2,
"devicetype": 2,
"dnt": 0,
"geo": {
"city": "Cityville",
"country": "USA",
"ipservice": 4,
"lat": 11.11,
"lon": -11.11,
"metro": "111",
"region": "NY",
"type": 2,
"utcoffset": -240,
"zip": "99999"
},
"ip": "2001:db8::1234",
"language": "en",
"lmt": 0,
"make": "Computster",
"model": "Computer",
"os": "Windows",
"osv": "9",
"pxratio": 21,
"ua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Chrome/114.0.0.0 "
},
"imp": [
{
"banner": {
"w": 728,
"h": 90,
"pos": 1,
"topframe": 0
},
"secure": 1,
"ext": {
"gpid": "/1234567/home/mpu/atf"
},
"id": "1",
"tagid": "12345_12345"
}
],
"user": {
"id": "AbcdEfgHijklmnoP",
"ext": {
"eids": [
{
"source": "ID_Provider.com",
"uids": [
{
"id": "Abcdefgh1234567Abcdefgh1234567Abcdefgh1234567Abcdefgh1234567Abcdefgh1234567"
}
]
},
{
"source": "Provider_id.org",
"uids": [
{
"id": "123456-abcde-123456-abcde-123456"
}
]
}
]
}
},
"regs": {
"ext": {
"gdpr": 0
}
}
} {
{
"app": {
"id": "885120",
"name": "Show TV",
"bundle": "MYBUNDLE",
"storeurl": "https://www.show.com/theshow",
"publisher": {
"id": "1234567",
"name": "Publisher Name"
},
"content": {
"cat": ["IAB1"],
"title": "The Show",
"genre": "entertainment",
"language": "en",
"len": 3600,
"livestream": 1,
"prodq": 1
},
"ext": {
"inventorypartnerdomain": "show.com"
}
},
"device": {
"connectiontype": 2,
"devicetype": 3,
"dnt": 0,
"geo": {
"city": "Mytown",
"country": "USA",
"ipservice": 4,
"lat": 22.2211,
"lon": -22.2211,
"metro": "501",
"region": "NY",
"type": 2,
"utcoffset": -240,
"zip": "99999"
},
"ifa": "aaaaaaaa-ebad-aaaa-aaaa-aaaaaaa",
"ip": "2001:0ab1:12a3:0000:0000:1a2b:1234:5678",
"language": "en",
"lmt": 0,
"make": "Movizon",
"model": "MovieStick",
"os": "Android",
"osv": "9",
"pxratio": 2,
"ua": "MovizonMovieStick/1.0 (AndroidOS 3.7; UAX64) FizzleEngine/9.4/123456"
},
"imp": [
{
"id": "1",
"bidfloor": 8,
"video": {
"w": 1920,
"h": 1080,
"placement": 1,
"plcmt": 1,
"pos": 7,
"mimes": ["video/mp4", "video/x-flv"],
"protocols": [2, 3, 5, 6],
"minduration": 5,
"maxduration": 60,
"linearity": 1,
"skip": 0
}
}
],
"user": {
"id": "aaaaaa-aaaa-aaaa-aaaa-aaaaaaaaa",
"ext": {
"eids": [
{
"source": "google.com",
"uids": [
{
"id": "123456-7891234-56789",
"atype": 1,
"ext": {
"rtiPartner": "anid"
}
}
]
},
{
"source": "id.com",
"uids": [
{
"id": "123456789",
"ext": {
"rtiPartner": "anotherid"
}
}
]
}
]
}
},
"regs": {
"coppa": 0,
"ext": {
"us_privacy": "1YNN"
}
},
"source": {
"fd": 0,
"pchain": "",
"ext": {}
}
} Response format (for both Cached API and Real-Time Data integrations)
The HTTP response should be in JSON format using the following structure:
| Object | Required? | Description | Format |
|---|---|---|---|
| segment_ids | Required |
The list of segments that are activated. Note: If there are no results, respond with an empty Note: A maximum of 500 segments can be sent in the array. |
Array of strings |
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 will not cache any data and the request will eventually be retried. If Index receives a 4xx error, Index caches information indicating that the request should not retried, and no enrichment data from the partner is available for the given key.
Circuit breaker logic
For both cached and cacheless partners, if Index receives a 4xx or 5xx error, Index's 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 will also trigger this same circuit breaker logic. Circuit breaker logic exists to protect both Index and our partners' systems. When errors rates return to nominal levels, circuit breakers will reopen and regular traffic volume will resume.
Cached API response headers
Index will honor the following HTTP response header for Cached API integrations.
| Object | Required? | Description |
|---|---|---|
| Cache-Control | Optional | The max-age directive is used to communicate how long the data can be used from cache. For partners implementing a cached integration with Index, if this directive is not supplied, we will cache the data for 24 hours and Index will not respect max-age directives exceeding 24 hours..
The no-cache directive will be used to communicate whether the data being returned should be re-validated before it is used again. Responses with this header will be cached, but any time that response is used, Index will reach out to the partner to determine whether the response has changed. This directive can be used while the partner's classification is running. |
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 their complete enrichment data.
"HTTP/1.1 200 OK
Server":"abc
Date":"Fri",
"31 Mar 2020 18":"37":"10 GMT
Content-Type":"text/html;charset=utf-8
Content-Length":"0
Connection":"keep-alive
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 with their endpoint for their complete enrichment data.
"HTTP/1.1 200 OK
Server":"abc
Date":"Fri",
"31 Mar 2020 18":"37":"10 GMT
Content-Type":"text/html;charset=utf-8
Content-Length":"0
Connection":"keep-alive
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 24h (86,000 seconds).
HTTP/1.1 200 OK
Server":"abc
Date":"Fri",
"31 Mar 2020 18":"37":"10 GMT
Content-Type":"text/html;charset=utf-8
Content-Length":"0
Connection":"keep-alive
Cache-Control":max-age=86400{
"segment_ids":[
"sports_news",
"football_players",
"arsenal",
"english_sports",
"fa_cup"
]
}
Authentication
If you require authentication, Index supports OAuth for both cached API and Real-Time Data integrations, as well as, tokens in the query string.
Frequently asked questions
Can I control when my segment data is used to enrich bids?
Yes. We offer simple QPS Queries Per Second (QPS). The number of bid requests a DSP processes per second. Also known as impressions per second. limits as well as the following more granular traffic shaping options:
-
Include or exclude specific domains, app bundles, countries, and device types
-
Include specific publishers and inventory channels
Who can use my segment data?
Segment permissions are strictly controlled by you. You can be the sole user of your segment data or permission it to another Marketplace or Publisher account.
What are the properties of a segment on Index?
-
Segment ID (matching data provider taxonomy)
-
Segment Name
-
Expiry information (in development)
-
Fee information (in development)
What updates can I expect soon?
Index will be adding the ability to add or update signals in the bid requests we send to DSPs based on the responses we receive from Data Partners. These updates may include:
-
Activating or suppressing specific deals.
-
Adjusting deal floors and other settings
-
Adding performance data to bid requests.
-
Additional price controls
