Skip to main content
API docs by Redocly

MediaGuard API

The MediaGuard API lets you send pre-bid data to HUMAN and receive IVT predictions accordingly. This HTTP-based API mirrors the core features of our gRPC-based SDK.

The MediaGuard API includes three endpoints:

  • The /v4/lookup endpoint expects a complete OpenRTB BidRequest object in its request body. MediaGuard analyzes the data in this object and returns an IVT prediction.

  • The default /lookup endpoint expects individual details about a bid request (extracted from an OpenRTB BidRequest object) in its request body. MediaGuard analyzes these details and returns an IVT prediction.
  • The /health-check endpoint checks the status of MediaGuard's servers.

Authentication

The MediaGuard API requires request-level authentication using Basic auth. 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.

Using curl

You can use curl to access the MediaGuard API. For example, the following command shows how to query the /v4/lookup endpoint using curl and basic HTTP authentication:

curl --location --request POST '/v4/lookup' \
--header 'Authorization: Basic <base64(username:password)>' \
--header 'Content-Type: application/json' \
--header 'Content-Encoding: gzip' \
--header 'Accept-Encoding: gzip' \
--data-raw '{
    "ortb": {...},
    "metadata": {...}
}'

Perform an ORTB lookup request [BETA]

Note: This endpoint is still in beta and subject to change at any time. Its final version may differ from the implementation described here.

Sends the full OpenRTB BidRequest object for 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 /v4/lookup endpoint only supports body encoding in JSON.

Authorizations:
humanAuth
header Parameters
Content-Encoding
string
Example: gzip

We recommend compressing your requests to the MediaGuard API. However, if your requests are compressed, you must add this header to inform MediaGuard's servers about the compression. (Note that only gzip compression is supported.)

Accept-Encoding
string
Example: gzip

You can also compress the responses returned by the MediaGuard API by adding this header to your requests. (Note that only gzip compression is supported.)

Request Body schema: application/json
ortb
required
object

The OpenRTB BidRequest object associated with the bid request that you'd like MediaGuard to analyze.

required
object

An object that contains additional key/value pairs with information to send to MediaGuard, including custom metadata. (Custom metadata is optional; however, the metadata object itself is not optional, since it contains the __supplier_id__ and __ortb_version__ fields, which are both required.)

Responses

Request samples

Content type
application/json
{
  • "ortb": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "80ce30c53c16e6ede735f123ef6e32361bfc7b22",
  • "lookupId": "b5f684df-f81e-9dd9-0102-b2f2d9a67ddc",
  • "ivt": true,
  • "serverId": "test-vm-1",
  • "ivtTaxonomy": [
    ],
  • "system": { },
  • "features": {
    }
}

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.

Authorizations:
humanAuth
header Parameters
Content-Type
string
Example: application/json

Specifies the body encoding for your lookup request; possible values are application/json and application/protobuf. If no type is specified, MediaGuard will expect JSON encoding by default.

Request Body schema: application/json
ip
required
string

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.

userAgent
required
string

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

url
required
string

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.

referer
string

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.

appId
string

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.

userId
string

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.

impressionId
string

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.

supplyChainObject
string

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

inventoryPartnerDomain
string

The domain of the authorized partner who owns the inventory that corresponds to the bid request. This value should match either the app.inventorypartnerdomain or site.inventorypartnerdomain field in the OpenRTB BidRequest object.

You should only include this parameter if the inventory is owned by an authorized partner (rather than the publisher themselves).

required
object

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

object

An object that contains additional information to send to MediaGuard.

Responses

Request samples

Content type
application/json
{
  • "ip": "127.127.127.5",
  • "userAgent": "Mozilla/5.0 (iPad; CPU OS 10_2 like Mac OS X)",
  • "url": "example.com/full/url/detail.html",
  • "referer": "sub.example.com/source",
  • "appId": "553834731",
  • "userId": "c3f927f4-3ef9-4b53-8887-d794c4daea82",
  • "impressionId": "a67e10e8-df61-44ef-b3bc-9a600e23e538",
  • "supplyChainObject": "1.0,1!exchange1.com,1234,1,bid-request-1,publisher,publisher.com",
  • "inventoryPartnerDomain": "partnerdomain.com",
  • "sortBy": {
    },
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "lookupId": "561356d9-b92f-4281-ba3a-7bc0448f066d",
  • "ivt": true,
  • "serverId": "test-vm-1",
  • "ivtTaxonomy": [
    ]
}

Check MediaGuard's status

Queries the current status of MediaGuard.

Note that this endpoint always returns an empty response body; you should use the HTTP response code to determine MediaGuard's current status.

Authorizations:
humanAuth

Responses