MediaGuard API
The MediaGuard HTTP API lets you send pre-bid data to HUMAN and receive IVT predictions accordingly. The MediaGuard HTTP service mirrors the core features of the gRPC service and lets you use any HTTP client to access the MediaGuard API.
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
.
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 'X-ORTB-VERSION: 2.6' \
--data-raw '{
"ortb": {...},
"metadata": {...}
}'
The MediaGuard API includes three endpoints:
- The
/v4/lookup
endpoint expects a complete OpenRTBBidRequest
object in its request body. MediaGuard analyzes the data in this ORTB object and returns an IVT prediction. - The default
/lookup
endpoint expects individual details about a bid request (extracted from an OpenRTBBidRequest
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.
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:
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 |
X-ORTB-VERSION required | string Example: 2.6 The OpenRTB version corresponding to the |
Request Body schema: application/json
ortb required | object The OpenRTB |
metadata | object Any custom key/value pairs that contain additional information you'd like to send to MediaGuard. |
Responses
Request samples
- Payload
{- "ortb": {
- "app": {
- "id": "52616",
- "ver": "2.006"
}, - "device": {
- "devicetype": 2,
- "ip": "109.193.225.182",
- "ua": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ''AppleWebKit/537.36 (KHTML, like Gecko) Chrome/106.0.0.0 ''Safari/537.36",
- "ifa": "97cef47f-085e-4b39-ba36-ba557f1d58a7"
}, - "id": "70e2524b-fe78-4928-a098-c5dba0451236",
- "site": {
- "ext": {
- "inventorypartnerdomain": "inventory_partner_domain object"
}
}, - "user": {
- "id": "4676071523872550819379"
}, - "ext": {
- "schain": {
- "complete": 1,
- "nodes": [
- {
- "asi": "yahoo.com",
- "hp": 1,
- "sid": "20459933223"
}, - {
- "asi": "triplelift.com",
- "hp": 1,
- "sid": "2792"
}
]
}
}
}, - "metadata": {
- "key": "value"
}
}
Response samples
- 200
{- "id": "80ce30c53c16e6ede735f123ef6e32361bfc7b22",
- "system": { },
- "lookupId": "561356d9-b92f-4281-ba3a-7bc0448f066d",
- "ivt": true,
- "serverId": "test-vm-1",
- "ivtTaxonomy": [
- "AB-BOT",
- "FR-EMU_RUD"
]
}
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. To choose between these content types, set the Content-Type
header to either application/json
or application/protobuf
as needed. If no type is specified, JSON is used by default.
Authorizations:
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 |
referer | string The full URL of the page that referred the user to the site of the event. This parameter follows the same formatting as the
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 |
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 |
userId | string A unique identifier that HUMAN uses to identify the user driving each event. For events 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 events until that user's cookies are cleared. |
impressionId | string A unique identifier that HUMAN uses to identify each event. You can set this parameter's value to the auction ID or impression ID for that event's bid request. This parameter is optional and helps us perform additional troubleshooting as needed. |
supplyChainObject | string A string-encoded representation of the OpenRTB |
required | object |
object |
Responses
Request samples
- Payload
{- "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",
- "sortBy": {
- "supplierId": "12345",
- "publisherId": "787656",
- "mediaType": "2",
- "deviceType": "4"
}, - "metadata": {
- "example-key": "example metadata value"
}
}
Response samples
- 200
{- "lookupId": "561356d9-b92f-4281-ba3a-7bc0448f066d",
- "ivt": true,
- "serverId": "test-vm-1",
- "ivtTaxonomy": [
- "AB-BOT",
- "FR-EMU_RUD"
]
}