> This page is for Advertising Protection.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.humansecurity.com/llms.txt.

# 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](/advertising/ad-click-defense/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](/advertising/ad-click-defense/deploy-detection-tag).
* For the real-time API, your platform must participate in the click redirection chain and be able to process HTTP or HTTPS API calls.

> **Note**
>
> HUMAN does not provide an SDK for the real-time API. You must implement your own server-to-server (S2S) integration code to send requests and process responses.

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

**`Example of a real-time Click IVT request payload`**

```sh showLineNumbers={false} Example of a real-time Click IVT request payload
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](/advertising/ad-click-defense/parameters#real-time-api-request-parameters) for detailed parameter descriptions.

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

**`Example of a real-time Click IVT response`**

```json showLineNumbers={false} Example of a real-time Click IVT response
{
    "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 enforcement 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](/advertising/ad-click-defense/parameters#click-ivt-taxonomy-codes) for detailed category descriptions.

## Next steps

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