How to use ClickPatrol API Tokens

The ClickPatrol API token gives you programmatic access to ClickPatrol's click-fraud intelligence. Instead of relying solely on the ClickPatrol dashboard, you can query any IP address directly from your own systems. 

Note: The API is currently in Beta. While it is fully functional, features and behaviour may change without notice. No technical support is provided for API usage at this time.

Requirements#

Before using the API, make sure you meet the following:

• You are on an active paid ClickPatrol plan. The API is not available on free or trial accounts
• You have access to your ClickPatrol dashboard in order to generate an API token
• You have a way to make HTTP GET requests (e.g. a server-side script, cron job, or HTTP client).

Generating Your API Token#

Each account has one API token at a time. To generate yours:

1. Log in to your ClickPatrol dashboard.
2. Navigate to your account settings or the API section of the dashboard.
3. Click Generate Token.
4. Your token will be displayed. Copy and store it somewhere secure, treat it like a password.

Important: If you regenerate your token, your existing token is immediately invalidated. Any integrations using the old token will stop working and must be updated with the new one.

Making an API Request#

Send an HTTP GET request to the following URL, replacing the placeholder values with real data:#

https://trck-003.clckptrl.com/?token={your_token}&ip={ip_address}&user_http_header={user_agent}

The following parameters are required or optional:#

• Token: Your unique API token. Generate this from your ClickPatrol dashboard.
• Ip: The IP address you want to assess. Must be a valid IPv4 or IPv6 address.
• user_http_header (Optional): The User-Agent string of the browser or client. Including this improves detection accuracy.

Example Request#

The following example shows how to call the API using cURL. This is commonly used in server-side cron jobs:

curl "https://trck-003.clckptrl.com/?token=cp_VwmZsQNSHAt6xRQNgFqO6XpLCo3W4loW&ip=103.138.188.159" \
  -H "User-Agent: Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X) AppleWebKit/605.1.15"

Replace the token value with your own token, and the IP address with the address you are checking.

The API returns a JSON object. Here is an example response:

{
  "trusted_ai_score": "Fake",
  "proxy": false,
  "tor": false,
  "vpn": false,
  "crawler": false,
  "bot": false
}

The response includes the trusted_ai_score, ClickPatrol's overall risk verdict for the IP. Possible values are Safe, Suspicious, and Fake (see below).

• Proxy: true if the IP is identified as a proxy server.
• Tor: true if the IP is a Tor exit node.
• Vpn: true if the IP is associated with a VPN service.
• Crawler: true if the IP belongs to a known web crawler or scraper.
• Bot: true if the IP is identified as automated bot traffic.

trusted_ai_score Values#

The trusted_ai_score field returns one of three values:

• Safe: The IP appears to be legitimate, human traffic. Allow the traffic normally.
• Suspicious: The IP shows some signs of invalid activity but is not conclusively fraudulent. Monitor closely and consider applying extra caution.
• Fake: The IP is identified as fraudulent or invalid traffic. This may indicate a bot, proxy, VPN, crawler, or other non-human source. Block or exclude this IP from your campaigns.
  

Click Usage and Fair Use#

Every request made to the API counts as one click and is deducted from your account's monthly click allowance; the same allowance used for your ClickPatrol campaign protection.

There are no separate API request tiers or rate limits beyond your monthly click balance. Once your monthly allowance is exhausted, API requests will not be processed until your allowance resets.