Real-Time Data Integration
How to enable the Scope3 real-time data provider
The Scope3 real-time data provider (RTDP) is a low latency (sub 10 ms) RESTful API that enables Ad Tech Platforms to retrieve Scope3 signals for real-time ad decisioning.
Segment Configuration
Before making requests to the Scope3 Real-Time Data Provider (RTDP), most Ad Tech platforms require segment objects to be pre-created with a defined name, category, and price. Ideally, we prefer API access to create and price segments automatically, eliminating the need for manual intervention. This streamlines the deployment process and enables faster activation of custom brand segments.
Requests to the Scope3 Real-time Data provider
Authentication
You will need an authentication key to use the real-time data provider (RTDP). This is different than the API keys used for the primary Scope3 API. Pass this key into a header with the key x-scope3-auth
.
Endpoints
We operate servers in several geographical regions globally. We suggest testing latencies from each of your data centers by hitting our /status
endpoint.
Endpoint | Location |
---|---|
rtdp.scope3.com | Global |
Regional-specific endpoints can be made available if needed, to ensure global coverage and low latency.
Input Parameters
The RTDP takes in parameters a JSON body that confines to the OpenRTB specifications or query string key-value pairs. We recommend partners to send full OpenRTB requests and ensuring that the below fields are present as they can impact the RTDP response.
Key | Example Value | OpenRTB Field | Priority |
---|---|---|---|
domain | yahoo.com | site.domain | ✅ Required |
appId | com.accuweather.android | app.bundle | ✅ Required |
page | https://www.nytimes.com/athletic/6125021/2025/02/09/super-bowl-2025-score-eagles-win-chiefs/ | site.page app.content.url | ✅ Required |
media_type | banner | imp.banner imp.video imp.audio imp.native | ✅ Required |
country | US | device.geo.country | ✅ Required |
region | CA | device.geo.region | 💡 Strongly Recommended |
city | Los Angeles | device.geo.city | 💡 Recommended |
metro | 803 | device.geo.metro | |
zip | 90049 | device.geo.zip | |
device_type | 2 | device.devicetype | ✅ Required |
user_agent | Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/134.0.0.0 Safari/537.36 | device.ua | 💡 Strongly Recommended |
gpid | /22888152279/us/yhp/main/dt/us_yhp_main_dt_top_center | imp[].ext.gpid | 💡 Strongly Recommended |
sellerPlacementId | rKbSuikdwy9UPfEwBcR8Pf6z | imp.tagid | |
sellerId | ifW4ft3g | app.publisher.id site.publisher.id | |
schain_nodes | [{"asi":"bluenetwork.com", "sid":"1200", "hp":1 }, {"asi":"exchange.com", "sid":"184033B", "hp":1 } ] | schain.nodes | 💡 Strongly Recommended |
exchange_sid | 96724 | schain.nodes.sid | |
exchange_name | example_exchange | schain.nodes.name | |
exchange_domain | example.com | schain.nodes.domain | |
eids | [{"source":"liveramp.com","uids":[{"id":"AvxfXjwFaie3SW…"}]}] | user.ext.eids | 💡 Strongly Recommended |
ctv_content_id | 4989112 | content.id | 💡 Recommended |
ctv_content_genre | adventure | content.genre | 💡 Recommended |
ctv_content_duration_seconds | 5437 | content.len | 💡 Recommended |
ctv_content_rating | G | content.contentrating | 💡 Recommended |
Routing and destinations
Some integration partners can support multiple destinations. For instance, Amazon Publisher Services can make a single request that routes responses to multiple SSPs. Similarly, some SSPs may be able to send segments to DSPs.
In these cases the destination will be specified using the canonical domain name of the SSP - the same domain that is used in the asi field in the OpenRTB supply chain object.
Output Response
Depending on ad platform, we can respond with deal ID, segment ID, or a combination. Incremental costs can be defined dynamically (as below) or configured in the underlying object.
Scope3 can support both segments and deal IDs in its response. Segments are generally preferred for multi-deal or multi-campaign implementations, but can also be used as a proxy for a specific deal ID.
Key | Example Value | Comment |
---|---|---|
segments | ["gmp_plus_eligible", "gmp_eligible", "fxj1", "gh23"] | The segments that are eligible for this request |
deal_ids | ["deal1234","deal2342"] | The deals that are eligible for this request |
segment_metadata | [{}, {}, {"weight": 1.28}, {"weight": 0.31}] | Metadata for each segment in the request |
deal_metadata | [{"max_bid": 5.00, "min_bid": 1.53}, {"min_bid": 0.28}] | Metadata for each deal ID in the request |
nurl | https://rtdp.scope3.com/nurl/auctionid={AUCTION_ID}&price=${AUCTION_PRICE}&status=delivered | The status field should be delivered for impressions delivered to the page, and won for impressions that are won in the ad platform |
Example multi-imp request & response
For an OpenRTB request with multiple impressions, like:
{
"site": {
"domain": "abcteach.com",
"publisher": {
"id": "cb8cfc89-e83e-44aa-a3a2-ff78eda781ef"
}
},
"imp": [
{
"id": 1,
"tagid": "/309850494/EZIP_ezyzip/home_header",
"ext": {
"gpid": "/22888152279/us/yhp/main/dt/us_yhp_main_dt_top_center"
}
},
{
"id": 2,
"tagid": "/309850494/EZIP_ezyzip/right_rectangle",
"ext": {
"gpid": "/22888152279/us/yhp/main/dt/us_yhp_main_right_rail"
}
}
],
"device": {
"devicetype": 2,
"geo": {
"country": "US"
},
"ua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36",
"ip": "15.248.7.128"
},
"schain": {
"nodes": [
{
"sid": "101",
"name": "Teaching Aids, LLC dba AdMetricsPro",
"domain": "admetricspro.com"
}
]
}
}
The response would be an array of data elements per configured destination:
"data": [
{
"destination": "indexexchange.com",
"imps": [
{
"id": 1,
"pmp": {
"deals": [
{
"id": "Deal1",
"ext": {
"min_bid": 13.13
}
},
{
"id": "Deal2",
}
],
},
"ext": {
"scope3": {
"segments": [
{
"id": "segment123",
"weight": 0.31
}
]
}
}
},
{
id: 2,
"pmp": {
...
},
"ext": {
...
}
}
]
},
{
"destination": "amazondsp.com",
"imps": [
{
"id": 1,
"ext": {
"scope3": {
"segments": [
{
"id": "segment183233",
"weight": 1.37
}
]
}
}
}
]
}
]
Win notifications
Scope3 exposes a web hook endpoint for notifications for every impression won delivered (the openrtb nurl
and burl
concepts). This endpoint expects at least auction ID and price, as well as a status field for delivered vs won. The Scope3 solutions team will help set this up to use available ad platform macros.
Log files
Scope3 expects a log file with official, billable impressions on at least a daily basis. This log file should include:
Field | Values | Example |
---|---|---|
QPS & scaling considerations
To ensure that using the Scope3 RTDP remains cost-effective and minimizes environmental impact, we recommend collaborating with our team to scale QPS caps as demand for the integration grows, and discuss how to best use the allocated QPS. Contact us to discuss this further.
Updated 18 days ago