MediaGuard APILookup

Perform a lookup request

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

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

The IP address of the device where the ad impression (and HUMAN’s detection tag) is intended to be delivered. This parameter expects the raw byte representation of the input address and accepts both IPv4 and IPv6 addresses.

userAgentstringRequired
The user agent of the user who drove the bid request.
urlstringRequired

The full URL of the site of the bid request.

Note that you must include either the url or appID parameter with each lookup request, but do not need to include both.

sortByobjectRequired
An object that contains additional information that HUMAN uses to categorize and sort bid request data.
refererstringOptional
The full URL of the page that referred the user to the site of the bid request. This parameter follows the same formatting as the `url` parameter. This parameter is exclusive to Desktop Web and Mobile Web environments. If a bid request originated from one of these environments, you **must** include the `referer` parameter in that bid's lookup request.
appIdstringOptional
The app bundle where the ad is intended to be delivered (for bid requests in Mobile App and CTV environments only). This parameter expects a valid string and should reflect OpenRTB bundle standards (*i.e.*, Android bundles are package names, while iOS bundles are usually numerical IDs). Note that you **must** include either the `url` or `appID` parameter with each lookup request, but do not need to include both.
userIdstringOptional

A unique identifier that HUMAN uses to identify the user driving each bid request.

For bid request in mobile environments, you should set this parameter’s value to the device’s iOS IDFA or Android AAID (when possible); for all other environments, you should generate a unique identifier that persists across all of that user’s bid request until that user’s cookies are cleared.

impressionIdstringOptional
A unique identifier that HUMAN uses to identify each bid request. You can set this parameter's value to the auction ID or impression ID for that bid request. This parameter is optional and helps us perform additional troubleshooting as needed.
supplyChainObjectstringOptional

A string-encoded representation of the bid request’s OpenRTB supplyChainObject.

inventoryPartnerDomainstringOptional
The domain of the authorized partner who owns the inventory that corresponds to the bid request. This value should match either the [`app.inventorypartnerdomain`](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md#3214---object-app-) or [`site.inventorypartnerdomain`](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md#3213---object-site-) field in the [OpenRTB `BidRequest` object](https://github.com/InteractiveAdvertisingBureau/openrtb2.x/blob/main/2.6.md#321---object-bidrequest-). You should only include this parameter if the inventory is owned by an authorized partner (rather than the publisher themselves).
metadataobjectOptional
An object that contains additional information to send to MediaGuard.

Response

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

lookupIdstring or null
The unique MediaGuard Prediction ID that corresponds to your lookup request.<p> If you're using the protobuf content type, keep in mind that the byte array representation of `lookupId` that's returned in the protobuf object/spec assumes little endian formatting. Some language methods (like .NET) use parsing methods that assume big endian formatting; however, you **must** use a parsing method that assumes little endian formatting.
ivtboolean or null

A Boolean value that, when true, indicates that HUMAN has identified the bid request as invalid traffic (IVT).

serverIdstring or null
The ID of the MediaGuard server that received your lookup request.
ivtTaxonomylist of strings or null
A list of IVT categories associated with the bid request. Can contain one or multiple values.

Errors