The MediaGuard API provides the endpoints you can use to assess ad impressions for fraud.
Authentication
The MediaGuard API requires request-level authentication using HTTP basic authentication. To authenticate a request, provide an Authorization header on your requests with the value Basic base64(username:password).
For example, if your HUMAN Auth ID is whiteops and your Auth Key is secret, your Authorization header should be set to Basic d2hpdGVvcHM6c2VjcmV0.
Using cURL
You can use cURL to access the MediaGuard API. The following command illustrates how to hit the MediaGuard API using cURL and basic HTTP authentication.
curl -u "username:password" -i https://example.<domain>.com/endpoint
Content type (JSON and Protocol Buffers)
All MediaGuard API endpoints support body encoding in both JSON and Protocol Buffers (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.
Endpoints
The following endpoints are available through the MediaGuard API.
Lookup request
Perform a lookup for the provided bid request details, which returns HUMAN's response of whether or not the bid request is a form of invalid traffic (IVT).
URL: /lookup
Method: POST
Success Response
Code: 200 OK
JSON
Content example: After performing the lookup request, HUMAN returned a “bot or not” decision:
{
"lookupId": "81d6f-a1b47e-44ed4768",
"ivt": true,
"serverId": "dev-vm",
"ivtTaxonomy": [
"<ivt code>"
]
}
Protobuf
Use the LookupResponse protobuf object. For details on implementing this object, please contact a HUMAN representative for access to our protobuf specification.
Error Response
Condition: Invalid argument provided.
Code: 400 BAD REQUEST
Content example:
error processing lookup: rpc error: code = InvalidArgument desc = Invalid request
Health request
Queries the health of the MediaGuard server.
URL: /health-check
Method: GET
Success Response
Code: 200 OK
Description: The MediaGuard server is ready to serve requests.
Error response
Code: 503 Service Unavailable
Description: The MediaGuard server is unavailable to server requests.