For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
HUMAN DashboardHUMAN WebsiteRequest a Demo
Media SecurityMalvertising DefenseAPI Reference
Media SecurityMalvertising DefenseAPI Reference
  • Reporting API
    • About the Reporting API
  • MediaGuard API
    • About the MediaGuard API
      • POSTPerform a lookup request
  • Malvertising API
    • POSTSubmit a creative for ad quality review
    • Push Result API overview
LogoLogo
Login
Login
HUMAN DashboardHUMAN WebsiteRequest a Demo
MediaGuard APILookup (v3)

Perform a lookup request

POST
https://your-mediaguard-server-url/lookup
POST
/lookup
$curl -X POST https://your-mediaguard-server-url/lookup \
>     -H "Content-Type: application/json" \
>     -u "<username>:<password>" \
>     -d '{}'
1{
2  "lookupId": "c58dbd91-6c3b-11e9-96bf-12c42e1e92dc",
3  "ivt": true,
4  "serverId": "50903d9b-169c-492f-8618-6fe079846c21",
5  "ivtTaxonomy": [
6    "AB"
7  ]
8}
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 filtration 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.
Was this page helpful?
Previous

Check MediaGuard's status

Next
Built with

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.

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

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

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.

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

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

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

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

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

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

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

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

Response

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

lookupIdstring

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
Indicates whether MediaGuard believes this impression to be bot activity or not.
serverIdstring
Identifies which specific MediaGuard server provided the lookup response.
ivtTaxonomylist of enums

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

400
Bad Request Error