Integrate real-time Click IVT response

This guide explains how to integrate the real-time Click IVT response analysis during click redirection. It assumes you have reviewed the integration options guide and selected the Observer-Path with real-time Click IVT response.

For the Observer-Path with real-time Click IVT response, both the HUMAN JavaScript detection tag and the real-time API are used in tandem.

Prerequisites

To integrate your platform with the real-time API, ensure you meet the following requirements:

• You have deployed the detection tag by following the instructions on deploying the detection tag.
• For the real-time API, your platform must participate in the click redirection chain and be able to process HTTPS API calls.

Integrate the real-time Click IVT response

Our API consists of a single endpoint: /lookup. Use this endpoint to pass information about individual clicks, one at a time, during click redirection. In response, the endpoint will return the corresponding IVT decision for each click. HUMAN will provide you with your API credentials and the exact endpoint URL.

curl --request POST \
    --url 'https://example.human.api.url/v4/lookup' \
    --header 'authorization: Basic <username>:<password>' \
    --header 'accept: application/json' \
    --header 'content-type: application/json' \
    --data '{
        "ip": "127.127.127.1",
        "userAgent": "Mozilla/5.0 (Linux; Android 12; SM-A217F Build/SP1A.210812.016; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/130.0.6723.107 Mobile Safari/537.36",
        "referer": "https://www.referer-site.com",
        "appId": "1234567890",
        "siteDomain": "example.com",
        "url": "https://www.example.com/full/url/detail.html",
        "deviceType": "2",
        "userId": "c3f927fdaea82",
        "sortBy": {
            "product": "clk",
            "mediaType": "1",
            "clientId": "772869",
            "supplierId": "12345",
            "publisherId": "67890"
        },
        "metadata": {
            "cache_key": "a67e10e800e23e538",
            "clk_ts": "1739571635000",
            "sus_ivt": "false",
            "imp_ts": "1739571650000",
            "lp": "example.com/full/url/detail.html"
        }
    }'

• Request Type: POST
• Authorization Header: authorization: Basic base64(<username>:<password>)
• Request Body: JSON payload containing the click telemetry. See Real-time API request parameters for detailed parameter descriptions.

The endpoint returns the corresponding invalid traffic detection for the click. If the request results in an error, it will return a 400 Bad Request.

{
    "lookupId": "6ef4e266f",
    "ivt": true,
    "policy": false,
    "serverId": "94e9fb71a",
    "ivtTaxonomy": ["GI-KC-DC_TAG"]
}

Response mapping:

• lookupId: A unique ID for the response generated by our real-time API.
• ivt: A boolean value. Use this to trigger your blocking logic.
  • true: Invalid click
  • false: Valid click
• policy: Indicates whether the click was detected as part of a custom policy.
• serverId: Unique server ID for debugging purposes.
• ivtTaxonomy: The specific Click IVT taxonomy code. See Click IVT Taxonomy for detailed category descriptions.

Next steps

After integrating the real-time API, contact a HUMAN representative for assistance with testing and validation.