> This page is for Advertising Protection.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.humansecurity.com/llms.txt.

# Perform a lookup request

POST https://YOUR-MEDIAGUARD-SERVER-URL/v4/lookup
Content-Type: application/json

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 filtration 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.

Reference: https://docs.humansecurity.com/advertising/reference/perform-lookup-request-4

## Authentication

- `Authorization` header (basic auth, required) — 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

### Body (application/json)

This endpoint expects a LookupRequest.

- `ip` (string, optional) — ORTB fieldCriticalOne of the most important fields used for IVT decisioning. 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`
- `userAgent` (string, optional) — ORTB fieldCriticalIdentifies 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`
- `distChannel` (enum, optional) — ORTB fieldCriticalIndicates 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: `site`, `app`, `dooh`
- `siteDomain` (string, optional) — ORTB fieldCriticalDomain of the site.**ORTB mapping:** `site.domain`
- `url` (string, optional) — ORTB fieldCriticalIdentifies 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`
- `appId` (string, optional) — ORTB fieldCriticalUsed 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`
- `appDomain` (string, optional) — ORTB fieldCriticalDomain of the mobile application.**ORTB mapping:** `app.domain`
- `appStoreurl` (string, optional) — ORTB fieldCriticalApp store URL for an installed app. For IQG 2.1 compliance.**ORTB mapping:** `app.storeurl`
- `doohDomain` (string, optional) — ORTB fieldCriticalDomain of the inventory owner.**ORTB mapping:** `dooh.domain`
- `supplyChainObject` (string, optional) — ORTB fieldCriticalThis 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`
- `referer` (string, optional) — ORTB fieldImportantProvides 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`
- `usrId` (string, optional) — ORTB fieldImportantExchange-specific ID for the user.**ORTB mapping:** `user.id`
- `usrBuyeruid` (string, optional) — ORTB fieldImportantBuyer-specific ID for the user as mapped by the exchange for the buyer.**ORTB mapping:** `user.buyeruid`
- `devIfa` (string, optional) — ORTB fieldImportantID 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`
- `inventoryPartnerDomain` (string, optional) — ORTB fieldImportantRequired 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`
- `srcTid` (string, optional) — ORTB fieldRecommendedTransaction ID that must be common across all participants in this bid request (e.g. potentially multiple exchanges).**ORTB mapping:** `source.tid`
- `appVersion` (string, optional) — ORTB fieldRecommendedApplication version.**ORTB mapping:** `app.ver`
- `sortBy` (LookupRequestSortBy, optional) — An object that contains additional information that HUMAN uses to categorize and sort bid request data.
- `metadata` (LookupRequestMetadata, optional) — MediaGuard fieldCustom metadata field/value pairs you define. Data is passed as a dictionary under the metadata parameter.
- `userId` (string, optional, deprecated) — 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`](#request.body.devIfa), [`usrId`](#request.body.usrId), and [`usrBuyeruid`](#request.body.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).
- `impressionId` (string, optional, deprecated) — ORTB field`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.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

### 200

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

- `lookupId` (string, optional) — 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.
- `ivt` (boolean, optional) — Indicates whether MediaGuard believes this impression to be bot activity or not.
- `policy` (boolean, optional) — Boolean representing the Policy decisioning of the MediaGuard platform. Removed Apps Enforcement is classified as a Policy decision; therefore, Removed Apps Enforcement decisions appear in this field.
- `serverId` (string, optional) — Identifies which specific MediaGuard server provided the lookup response.
- `ivtTaxonomy` (list of enum, optional) — An array of strings representing all IVT classifications of the lookup request. Each string is formatted in the following manner: `GI-{Category}-{Subcategory}` or `SI-{Category}-{Subcategory}`. `GI` represents that this is classified as GIVT (generalized invalid traffic). `SI` represents that this is classified as SIVT (sophisticated invalid traffic). For descriptions of the IVT categories and subcategories, see the [IVT Taxonomy](/advertising/ivt-taxonomy) documentation. See also [IVT & Policy Reason Codes](/advertising/ivt-taxonomy-reason-codes).
  - Allowed values: `GI-DC-NO_VPN`, `GI-DC-TAG_IP`, `GI-FR-INV_TRA`, `GI-FR-INV_TRA_BLANK_UA`, `GI-FR-INV_TRA_MALF_UA`, `GI-IP-REP_TRX`, `GI-KC-AI`, `GI-KC-CS`, `GI-KC-IAB_SPI_AL`, `GI-KC-IAB_SPI_BL`, `GI-KC-HMN`, `GI-MUI-INV_PL`, `SI-AB`, `SI-AB-AB`, `SI-AB-BOT`, `SI-FR`, `SI-FR-ADS_TXT`, `SI-FR-ADS_TXT_L1`, `SI-FR-APP_ADS`, `SI-FR-APP_ADS_L1`, `SI-FR-APP_SPO`, `SI-FR-BID_PRA_MIS`, `SI-FR-DOM_SPO`, `SI-FR-EMU_RUD`, `SI-FR-PRA_MIS`, `SI-FR-PRA_MIS_ENV`, `SI-FR-SPO_MEA`, `SI-MB-ATT_MAN`, `SI-MUI`, `SI-MUI-AD_HID`, `SI-MUI-CLI`, `SI-MUI-POP`, `SI-MUI-STA_ADS`, `SI-UC`, `SI-UC-IVT_ML`, `SI-UUI-CLI_FRM`, `SI-UUI-PAY_CLI`
- `policyTaxonomy` (list of string, optional) — An array of strings representing the non-IVT classifications of the lookup request. Each string is formatted as `PL-{Category}-{Subcategory}`.
- `overriddenTaxonomy` (list of string, optional) — An array of strings representing all taxonomies that would trigger a decision that has been overridden via a Policy allow list. Each string is formatted as `{PL}-{Category}-{Subcategory}`, `{GI}-{Category}-{Subcategory}`, or `{SI}-{Category}-{Subcategory}`.

## Errors

### 400 Bad Request Error

Invalid argument provided.

- `string`

## Types

### LookupRequestSortBy

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

- `supplierId` (string, optional) — MediaGuard fieldCriticalUsed to identify the supplier of the impression. This value should be the domain of the ad system that created the current version of the bid request that corresponds to the impression. This value should match the first field of the associated entry in the publisher’s `ads.txt` or `app-ads.txt` file. If you are a supply-side platform (SSP), this is usually your own domain. MediaGuard uses this information to specifically target fraudulent suppliers.
- `publisherId` (string, optional) — ORTB fieldCriticalThe Publisher ID of the traffic source. Used to differentiate specific sets of fraudulent traffic. This value is the current seller of the ad inventory. This value must be consistent with OpenRTB's Publisher ID and **should match the value in the second field of the `ads.txt file`.** One or more Publisher IDs will correspond to a single Supplier ID.**ORTB mapping:** `app.publisher.id` | `site.publisher.id`
- `mediaType` (enum, optional) — ORTB fieldCriticalThe media type is used to identify the type of impression. It is used to identify sub-sets of invalid traffic. It is also used for reporting in the Dashboard. You must provide an integer value **as a string** based on which of the `banner`, `video`, `audio`, or `native` fields are populated in each of the impression objects in the `imp[]` OpenRTB 3.2.4 array.| Value | Description | OpenRTB Reference | | ----- | ---------------------------------------------------------------------------- | ----------------- | | 1 | Banner | 3.2.6 | | 2 | Video | 3.2.7 | | 3 | Audio | 3.2.8 | | 4 | Native | 3.2.9 | | 5 | If multiple fields are populated in one impression object or across multiple | |
  - Allowed values: `1`, `2`, `3`, `4`, `5`
- `deviceType` (enum, optional) — ORTB fieldImportantThe device type is used to identify the type of device on which the impression is running and sub-sets of invalid traffic. It is also used for reporting in the Dashboard. Provide an integer value for the device type **as a string** per the following mapping.| Value | Description | Example | | ----- | -------------------------- | ------------------------------------------ | | 1 | Mobile/Tablet - General | iPhone X (legacy should use 4), iPad | | 2 | Personal Computer | Windows 10, MacOS Mojave | | 3 | Connected TV | Samsung, Sony, Vizio | | 4 | Phone | iPhone X, Nexus 5 | | 5 | Tablet | iPad | | 6 | Connected Device | Roku, Apple TV, Fire TV, Xbox, PlayStation | | 7 | Set Top Box | Canoe, Comcast, Broadcom | | 8 | Digital Out Of Home (DOOH) | |**ORTB mapping:** `device.devicetype`
  - Allowed values: `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`

### LookupRequestMetadata

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

- `example-key` (string, optional) — Any custom metadata (in the form of key/value pairs) that you'd like to include in each lookup request. As part of your MediaGuard integration, we may recommend that you send this extra data to HUMAN's servers for enhanced reporting data and easier troubleshooting.

## Examples

**Request**

```json
{}
```

**Response**

```json
{
  "lookupId": "c58dbd91-6c3b-11e9-96bf-12c42e1e92dc",
  "ivt": true,
  "policy": true,
  "serverId": "50903d9b-169c-492f-8618-6fe079846c21",
  "ivtTaxonomy": [
    "GI-DC-TAG_IP"
  ],
  "policyTaxonomy": [
    "PL-MFA-MFA"
  ]
}
```

**SDK Code**

```python Success
import requests

url = "https://your-mediaguard-server-url/v4/lookup"

payload = {}
headers = {
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers, auth=("<username>", "<password>"))

print(response.json())
```

```javascript Success
const url = 'https://your-mediaguard-server-url/v4/lookup';
const credentials = btoa("<username>:<password>");

const options = {
  method: 'POST',
  headers: {
    Authorization: `Basic ${credentials}`,
    'Content-Type': 'application/json'
  },
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Success
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://your-mediaguard-server-url/v4/lookup"

	payload := strings.NewReader("{}")

	req, _ := http.NewRequest("POST", url, payload)

	req.SetBasicAuth("<username>", "<password>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Success
require 'uri'
require 'net/http'

url = URI("https://your-mediaguard-server-url/v4/lookup")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request.basic_auth("<username>", "<password>")
request["Content-Type"] = 'application/json'
request.body = "{}"

response = http.request(request)
puts response.read_body
```

```java Success
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://your-mediaguard-server-url/v4/lookup")
  .basicAuth("<username>", "<password>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

```php Success
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://your-mediaguard-server-url/v4/lookup', [
  'body' => '{}',
  'headers' => [
    'Content-Type' => 'application/json',
  ],
    'auth' => ['<username>', '<password>'],
]);

echo $response->getBody();
```

```csharp Success
using RestSharp;
using RestSharp.Authenticators;

var client = new RestClient("https://your-mediaguard-server-url/v4/lookup");
client.Authenticator = new HttpBasicAuthenticator("<username>", "<password>");
var request = new RestRequest(Method.POST);

request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Success
import Foundation

let credentials = Data("<username>:<password>".utf8).base64EncodedString()

let headers = [
  "Authorization": "Basic \(credentials)",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://your-mediaguard-server-url/v4/lookup")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```