Fraud API

The Fraud API returns the real-time probability of invalid traffic (IVT) for an IP address, device ID or user agent, plus the risk type codes that explain why it’s flagged. Use it to decide whether a value is compromised before you bid on, serve or pay for an impression.

Each lookup draws on Pixalate’s continuously updated fraud intelligence across mobile, CTV and web. You set your own blocking threshold, so you can match it to your supply and risk tolerance.

Before you start

Make your first request

Send the value you want to check as a query parameter. This example checks one IPv4 address:

curl --get "https://fraud-api.pixalate.com/api/v3/fraud" \
  -H "x-api-key: $PIXALATE_API_KEY" \
  --data-urlencode "ip=198.51.100.7" \
  --data-urlencode "pretty=true"

The API returns a FraudInfo object:

{
  "probability": 0.92,
  "riskTypes": [2502, 2201]
}

This response is illustrative. The values you get back depend on Pixalate’s data for the value you send.

Query parameters

All parameters are optional. Send any combination of ip, deviceId and userAgent.

If you send more than one value, probability reflects the combined risk of all the values you sent, and riskTypes lists the risk types for all of them.

curl --get "https://fraud-api.pixalate.com/api/v3/fraud" \
  -H "x-api-key: $PIXALATE_API_KEY" \
  --data-urlencode "ip=198.51.100.7" \
  --data-urlencode "deviceId=00000000-0000-4000-8000-000000000000" \
  --data-urlencode "userAgent=Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"

Read the response

Some rules for riskTypes:

• It’s null when probability is 0 or -1.
• It’s null when a value is flagged but no risk type is available for it.
• It’s never an empty array, and it doesn’t repeat a code.

Only a small number of IP addresses and device IDs are whitelisted, so you’ll rarely see -1.

To find out what each code means, see Risk types and codes.

Example responses:

{ "probability": 0, "riskTypes": null }

Decide when to block

Block with a probability threshold

Pixalate’s proprietary machine-learning algorithm calculates the probability, so you can set your own threshold based on the quality and scale of your supply inventory. As a guide:

Block with risk types

Risk types tell you why a value is flagged. You can use them in blocking rules on their own or together with a probability threshold, at any level of the code: all SIVT (2xxx), one category (25xx) or a single type (2502). See Risk types and codes for the code format.

For example, this rule blocks a value when the probability is 0.90 or higher, or when any risk type is in the 25xx category:

def should_block(result: dict) -> bool:
    if result.get("probability", 0) >= 0.90:
        return True
    codes = result.get("riskTypes") or []
    return any(code // 100 == 25 for code in codes)

Treat riskTypes: null as “no codes”, not as “not flagged”. Always check probability too.

Check your quota

Call the endpoint without ip, deviceId or userAgent to get your account’s quota status instead of a lookup:

curl "https://fraud-api.pixalate.com/api/v3/fraud?pretty=true" \
  -H "x-api-key: $PIXALATE_API_KEY"

{
  "used": 5000,
  "limit": 10000,
  "available": 5000,
  "unlimited": false,
  "interval": 30,
  "timeUnit": "day",
  "expiry": "2026-11-13T00:00:00.000Z"
}

Errors

For limits and errors across all Pixalate APIs, see Quotas, limits and errors.

Related