This document outlines guidelines for implementing HTTP-based real-time data integrations.
Note: This implementation supports signal enrichment only. Existing integrations remain supported, but no new capabilities will be added.
Request formats
Partners using a Real-Time Data integration must expose an endpoint A URL which is configured to interact with a server in a specific way. accessible through an HTTP POST request, where Index will use the following 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 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.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": [
{
"id": "1",
"tagid": "12345_12345",
"banner": {
"w": 728,
"h": 90,
"pos": 1,
"topframe": 0
},
"secure": 1,
"gpid": "/1234567/home/mpu/atf"
}
],
"user": {
"id": "AbcdEfgHijklmnoP",
"eids": [
{
"source": "ID_Provider.com",
"uids": [
{
"id": "Abcdefgh1234567Abcdefgh1234567Abcdefgh1234567Abcdefgh1234567Abcdefgh1234567"
}
]
},
{
"source": "Provider_id.org",
"uids": [
{
"id": "123456-abcde-123456-abcde-123456"
}
]
}
]
},
"regs": {
"coppa": 0,
"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",
"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",
"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
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
A 2xx HTTP response code should be returned for successful responses from all partners..
Circuit breaker logic
If Index receives a 4xx or 5xx error or more than 5% of requests have exceeded a timeout value of 5ms, 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.
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, tokens in the query string or a token in the request header. We can also provide IP ranges for allow-listing, but they may change over time and require regular updates.
