[v3] Perform a lookup request | HUMAN Documentation

Sends details about a specific bid request to MediaGuard, then returns HUMAN’s analysis of whether the bid request is a form of invalid traffic (IVT). Parameters are categorized by urgency and should be included accordingly.

Critical: This parameter is essential for effective detection and filteration of invalid traffic. It must be included in the request for effective performance.
Important: This parameter is significant for effective detection and performance, but is not as strictly required as those marked Critical.
Recommended: This parameter is not essential, but can provide additional useful context for the prediction.

The request body parameters below are marked as optional because the response returns 200 OK even if you do not send any parameters. However, failure to, at minimum, supply parameters marked as Critical will significantly interfere with MediaGuard’s ability to effectively detect and filter invalid traffic.

Content type

The /lookup endpoint supports body encoding in both JSON and protobuf. You can use the Content-Type header to specify which type you’re using.

Sends details about a specific bid request to MediaGuard, then returns HUMAN's analysis of whether the bid request is a form of invalid traffic (IVT). Parameters are categorized by urgency and should be included accordingly. * <Badge intent="error" minimal outlined>Critical</Badge>: This parameter is essential for effective detection and filteration of invalid traffic. It must be included in the request for effective performance. * <Badge intent="warning" minimal outlined>Important</Badge>: This parameter is significant for effective detection and performance, but is not as strictly required as those marked Critical. * <Badge intent="success" minimal outlined>Recommended</Badge>: This parameter is not essential, but can provide additional useful context for the prediction. <Warning> The request body parameters below are marked as **optional** because the response returns `200 OK` even if you do not send any parameters. However, failure to, at minimum, supply parameters marked as <Badge intent="error" minimal outlined>Critical</Badge> will significantly interfere with MediaGuard's ability to effectively detect and filter invalid traffic. </Warning> ### Content type The `/lookup` endpoint supports body encoding in both JSON and protobuf. You can use the `Content-Type` header to specify which type you're using.

Authentication

AuthorizationBasic

To authenticate a request, provide an Authorization header with the value Basic base64(username:password). For example, if your HUMAN Auth ID is whiteops and your HUMAN Auth Key is secret, your Authorization header should be set to Basic d2hpdGVvcHM6c2VjcmV0.

Request

This endpoint expects an object.

ipstringOptional

ORTB field Critical

One of the most important fields used for blocking. Provide full IPv4 or IPv6 address. If the least significant byte is truncated, this will be less effective compared to full IP address. However, it is still required.

ORTB mapping: device.ip | device.ipv6

<Badge intent="info">ORTB field</Badge> <Badge intent="error" minimal outlined>Critical</Badge> One of the most important fields used for blocking. Provide full IPv4 or IPv6 address. If the least significant byte is truncated, this will be less effective compared to full IP address. However, it is still required. **ORTB mapping:** `device.ip` | `device.ipv6`

userAgentstringOptional

ORTB field Critical

Identifies the browser and OS in which the environment is running. This is used by MediaGuard to identify false, misconfigured, or malicious environments. Provide the full User Agent of where the event originated or the ad will be served.

ORTB mapping: device.ua

<Badge intent="info">ORTB field</Badge> <Badge intent="error" minimal outlined>Critical</Badge> Identifies the browser and OS in which the environment is running. This is used by MediaGuard to identify false, misconfigured, or malicious environments. Provide the full User Agent of where the event originated or the ad will be served. **ORTB mapping:** `device.ua`

distChannelenumOptional

ORTB field Critical

Indicates which of the mutually-exclusive top level distribution channel objects, site, app, or dooh, are populated in the OpenRTB bid request. Based on which is populated, distChannel should be set to a string of that field’s name.

<Badge intent="info">ORTB field</Badge> <Badge intent="error" minimal outlined>Critical</Badge> Indicates which of the mutually-exclusive top level distribution channel objects, `site`, `app`, or `dooh`, are populated in the OpenRTB bid request. Based on which is populated, `distChannel` should be set to a string of that field’s name.

Allowed values:

siteDomainstringOptional

ORTB field Critical

Domain of the site.

ORTB mapping: site.domain

urlstringOptional

ORTB field Critical

Identifies the URL that the user is visiting. This is the URL of the page where the ad placement event originated. Include the protocol (scheme), host, port (if applicable), and path. Query, GET parameters, or fragments can be excluded.

ORTB mapping: site.page

<Badge intent="info">ORTB field</Badge> <Badge intent="error" minimal outlined>Critical</Badge> Identifies the URL that the user is visiting. This is the URL of the page where the ad placement event originated. Include the protocol (scheme), host, port (if applicable), and path. Query, GET parameters, or fragments can be excluded. **ORTB mapping:** `site.page`

appIdstringOptional

ORTB field Critical

Used to specify the mobile application running the advertisement. In combination with the URL parameter, this can be used to identify whether all or some of an app’s behavior is fraudulent. For In-App Mobile or CTV traffic, provide the App ID/Bundle ID and maintain case. Do not alter case by changing all to lowercase or all to uppercase. Values should conform to the IAB Tech Lab App Identification Guidelines.

ORTB mapping: app.bundle

<Badge intent="info">ORTB field</Badge> <Badge intent="error" minimal outlined>Critical</Badge> Used to specify the mobile application running the advertisement. In combination with the URL parameter, this can be used to identify whether all or some of an app's behavior is fraudulent. For In-App Mobile or CTV traffic, provide the App ID/Bundle ID and maintain case. Do not alter case by changing all to lowercase or all to uppercase. Values should conform to the [IAB Tech Lab App Identification Guidelines](https://iabtechlab.com/wp-content/uploads/2020/08/IAB-Tech-Lab-OTT-store-assigned-App-Identification-Guidelines-2020.pdf). **ORTB mapping:** `app.bundle`

appDomainstringOptional

ORTB field Critical

Domain of the mobile application.

ORTB mapping: app.domain

appStoreurlstringOptional

ORTB field Critical

App store URL for an installed app. For IQG 2.1 compliance.

ORTB mapping: app.storeurl

doohDomainstringOptional

ORTB field Critical

Domain of the inventory owner.

ORTB mapping: dooh.domain

supplyChainObjectstringOptional

ORTB field Critical

This field is not defined in OpenRTB 2.5. Bid requests using earlier OpenRTB versions will find the supplyChainObject under source.ext.schain.

The SupplyChain Object, otherwise known as schain, is a part of an OpenRTB bid request and consists of “nodes.” Each node in the schain object represents a specific entity participating in the bid request, which includes all entities involved in the direct flow of payment for inventory. SupplyChain Object removes anonymity in the supply chain.

The supplyChainObject field expects the syntactically correct value, following the IAB standard and Serialization method. Additionally please refer to the following:

In case you are an SSP:
- Direct Inventory: Construct new SChain node containing only your node
- Resold Inventory: Add your node to SChain received from upstream source
- Ensure accuracy by sending what is in the bid request you send downstream.
In case you are a DSP, send the full SupplyChain Object received from upstream SSPs.

ORTB mapping: source.schain

<Badge intent="info">ORTB field</Badge> <Badge intent="error" minimal outlined>Critical</Badge> <Note> This field is not defined in OpenRTB 2.5. Bid requests using earlier OpenRTB versions will find the supplyChainObject under `source.ext.schain`. </Note> The SupplyChain Object, otherwise known as schain, is a part of an OpenRTB bid request and consists of "nodes." Each node in the schain object represents a specific entity participating in the bid request, which includes all entities involved in the direct flow of payment for inventory. SupplyChain Object removes anonymity in the supply chain. The supplyChainObject field expects the syntactically correct value, following the IAB standard and Serialization method. Additionally please refer to the following: * In case you are an SSP: * **Direct Inventory:** Construct new SChain node containing only your node * **Resold Inventory:** Add your node to SChain received from upstream source * Ensure accuracy by sending what is in the bid request you send downstream. * In case you are a DSP, send the full SupplyChain Object received from upstream SSPs. **ORTB mapping:** `source.schain`

refererstringOptional

ORTB field Important

Provides MediaGuard with information about the source of this traffic and what site directed or referred the user to the current page. Provide the full referer, which is the full URL/Host of where the user was prior to the current page where the event originated.

ORTB mapping: site.ref

<Badge intent="info">ORTB field</Badge> <Badge intent="warning" minimal outlined>Important</Badge> Provides MediaGuard with information about the source of this traffic and what site directed or referred the user to the current page. Provide the full referer, which is the full URL/Host of where the user was prior to the current page where the event originated. **ORTB mapping:** `site.ref`

usrIdstringOptional

ORTB field Important

Exchange-specific ID for the user.

ORTB mapping: user.id

usrBuyeruidstringOptional

ORTB field Important

Buyer-specific ID for the user as mapped by the exchange for the buyer.

ORTB mapping: user.buyeruid

devIfastringOptional

ORTB field Important

ID sanctioned for advertiser use in the clear (i.e. not hashed). Unless prior arrangements have been made between the buyer and the seller directly, the value in this field is expected to be an ID derived from a call to an advertising API provided by the device’s operating system.

ORTB mapping: device.ifa

<Badge intent="info">ORTB field</Badge> <Badge intent="warning" minimal outlined>Important</Badge> ID sanctioned for advertiser use in the clear (i.e. not hashed). Unless prior arrangements have been made between the buyer and the seller directly, the value in this field is expected to be an ID derived from a call to an advertising API provided by the device's operating system. **ORTB mapping:** `device.ifa`

inventoryPartnerDomainstringOptional

ORTB field Important

Required to accurately determine if the sellers of certain inventory are ads.txt/app-ads.txt authorized. While it was added to the standards with CTV in mind, it is not limited to CTV—it can be used by any type of inventory, including web and mobile.

The value of this field should be the top level domain hosting the ads.txt file for the inventory partner that owns this ad inventory. With inventoryPartnerDomain, the partner must always host an ads.txt, not an app-ads.txt, even for app inventory (e.g. app-developer.com/app-ads.txt contains INVENTORYPARTNERDOMAIN=partner.com, which is resolved to partner.com/ads.txt).

Sites should list all partners (via INVENTORYPARTNERDOMAIN variables) in their ads.txt files. Similarly, apps should list all partners in their app-ads.txt files. The MediaGuard lookup request must contain only the single partner that owns the specific inventory the request is for if, and only if, the inventory is owned by a partner and not the site/app itself.

ORTB mapping: app.inventorypartnerdomain | site.inventorypartnerdomain

<Badge intent="info">ORTB field</Badge> <Badge intent="warning" minimal outlined>Important</Badge> Required to accurately determine if the sellers of certain inventory are ads.txt/app-ads.txt authorized. While it was added to the standards with CTV in mind, it is not limited to CTV—it can be used by any type of inventory, including web and mobile. The value of this field should be the top level domain hosting the ads.txt file for the inventory partner that owns this ad inventory. With `inventoryPartnerDomain`, the partner must always host an ads.txt, not an app-ads.txt, even for app inventory (e.g. `app-developer.com/app-ads.txt` contains `INVENTORYPARTNERDOMAIN=partner.com`, which is resolved to `partner.com/ads.txt`). Sites should list all partners (via `INVENTORYPARTNERDOMAIN` variables) in their ads.txt files. Similarly, apps should list all partners in their app-ads.txt files. The MediaGuard lookup request must contain only the single partner that owns the specific inventory the request is for if, and only if, the inventory is owned by a partner and not the site/app itself. **ORTB mapping:** `app.inventorypartnerdomain` | `site.inventorypartnerdomain`

srcTidstringOptional

ORTB field Recommended

Transaction ID that must be common across all participants in this bid request (e.g. potentially multiple exchanges).

ORTB mapping: source.tid

appVersionstringOptional

ORTB field Recommended

Application version.

ORTB mapping: app.ver

sortByobjectOptional

An object that contains additional information that HUMAN uses to categorize and sort bid request data.

metadataobjectOptional

MediaGuard field

Custom metadata field/value pairs you define. Data is passed as a dictionary under the metadata parameter.

userIdstringOptionalDeprecated

ORTB field

userId has been deprecated as of v3.0. To address the ambiguity between different IDs that this field accommodated, three individual fields are introduced in the new API: devIfa, usrId, and usrBuyeruid.

A user-resettable unique identifier that lets HUMAN track a user session across multiple visits/impressions. User characteristics are modeled as part of the MediaGuard bot detection algorithms. For mobile traffic, provide Device ID—IDFA (iOS) or AAID (Android). For web traffic provide User ID (cookie or unique identifier internal to client system).

<Badge intent="info">ORTB field</Badge> <Warning> `userId` has been deprecated as of v3.0. To address the ambiguity between different IDs that this field accommodated, three individual fields are introduced in the new API: [`devIfa`](#request.body.devIfa), [`usrId`](#request.body.usrId), and [`usrBuyeruid`](#request.body.usrBuyeruid). </Warning> A user-resettable unique identifier that lets HUMAN track a user session across multiple visits/impressions. User characteristics are modeled as part of the MediaGuard bot detection algorithms. For mobile traffic, provide Device ID—IDFA (iOS) or AAID (Android). For web traffic provide User ID (cookie or unique identifier internal to client system).

impressionIdstringOptionalDeprecated

ORTB field

impressionId has been deprecated as of v3.0 and replaced with srcTid unless it is specifically needed to join MediaGuard requests to FraudSensor impressions.

Used to tie information from the client side to the back-end data on the HUMAN system.

ORTB mapping: source.tid when available, otherwise fall back to id

<Badge intent="info">ORTB field</Badge> <Warning> `impressionId` has been deprecated as of v3.0 and replaced with [`srcTid`](#request.body.srcTid) unless it is specifically needed to join MediaGuard requests to FraudSensor impressions. </Warning> Used to tie information from the client side to the back-end data on the HUMAN system. **ORTB mapping:** `source.tid` when available, otherwise fall back to `id`

Response

Successful lookup request that returns HUMAN’s “bot or not” decision:

lookupIdstring or null

A UUID (string in HTTP response, []byte in gRPC response) value that represents this specific MediaGuard response. Also commonly referred to as the “Prediction ID”. This value should be passed to FraudSensor via the pv parameter.

ivtboolean or null

Indicates whether MediaGuard believes this impression to be bot activity or not.

serverIdstring or null

Identifies which specific MediaGuard server provided the lookup response.

ivtTaxonomylist of enums or null

A list of strings identifying the IVT reason codes associated with this particular lookup. Reason codes are provided for ivt: true responses. Hover over each code for their classification (GIVT or SIVT) and definition.

Errors

ORTB field Important

ORTB mapping: app.inventorypartnerdomain | site.inventorypartnerdomain

1	import requests
2
3	url = "https://your-mediaguard-server-url/lookup"
4
5	payload = {}
6	headers = {
7	"Authorization": "Basic <username>:<password>",
8	"Content-Type": "application/json"
9	}
10
11	response = requests.post(url, json=payload, headers=headers)
12
13	print(response.json())

1	{
2	"lookupId": "c58dbd91-6c3b-11e9-96bf-12c42e1e92dc",
3	"ivt": true,
4	"serverId": "50903d9b-169c-492f-8618-6fe079846c21",
5	"ivtTaxonomy": [
6	"AB"
7	]
8	}