> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.pixalate.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pixalate.com/_mcp/server.

# Fraud API

> Use Pixalate's Fraud API v3 to get the probability of invalid traffic (IVT) and the risk type codes for an IP address, device ID or user agent.

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.

> **Note**
>
> This page covers Fraud API v3, the current version. v2 is still available as a legacy API. To move from v2, see [Migrate from v2 to v3](/apis/fraud-api-v2-to-v3).

## Before you start

| What     | Value                                                                                                                                             |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| API key  | Sign up at the [Pixalate developer portal](https://developer.pixalate.com) to get a key. See [Authentication and API keys](/apis/authentication). |
| Auth     | Send your key in the `x-api-key` request header.                                                                                                  |
| Base URL | `https://fraud-api.pixalate.com/api/v3`                                                                                                           |
| Endpoint | `GET /fraud`                                                                                                                                      |

## Make your first request

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

```bash
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:

```json
{
  "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`.

| Parameter   | What to send                                                                                                                                                                                               |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ip`        | An IPv4 or IPv6 address.                                                                                                                                                                                   |
| `deviceId`  | A mobile or CTV device ID: ADID (Android), IDFA (iOS), RIDA (Roku OS), MSAI (Xbox), WAID (Windows), or an MD5 or SHA-1 hash of a hardware device identifier such as a MAC address, IMEI or advertising ID. |
| `userAgent` | The user agent string sent by the browser or device. URL-encode it.                                                                                                                                        |
| `pretty`    | `true` returns indented JSON. Default is `false`.                                                                                                                                                          |

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.

```bash
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

| Field         | Type                         | What it tells you                                                                                                                                                                                     |
| ------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `probability` | number                       | How likely the value is to be associated with fraud or invalid traffic, up to `1.0`. `0` means Pixalate's fraud intelligence system doesn't flag it. `-1` means the value is whitelisted by Pixalate. |
| `riskTypes`   | array of integers, or `null` | The four-digit risk type codes associated with the values you sent during the look-back period. It can contain more than one code.                                                                    |

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](/apis/fraud-api-risk-types).

Example responses:

#### Not flagged

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

#### Whitelisted

```json
{ "probability": -1, "riskTypes": null }
```

#### Several values sent

```json
{ "probability": 0.994, "riskTypes": [2205, 2202, 2207] }
```

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

| Probability                             | What you filter out                                 |
| --------------------------------------- | --------------------------------------------------- |
| `1.0`                                   | Only the worst offenders (deterministic).           |
| `0.90` or higher                        | Users who are fraudulent beyond a reasonable doubt. |
| `0.75` up to, but not including, `0.90` | Users with clear and convincing evidence of fraud.  |
| `0.5` up to, but not including, `0.75`  | Users who are more likely than not fraudulent.      |
| `0`                                     | Nothing. The value isn't flagged.                   |
| `-1`                                    | Nothing. The value is whitelisted by Pixalate.      |

> **Warning**
>
> Pixalate doesn't recommend blocking any probability below `0.5`. If you adjust your threshold, check impression delivery regularly, because lowering the threshold can reduce impression counts.

### 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](/apis/fraud-api-risk-types) 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:

```python
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:

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

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

| Field       | What it tells you                                                                                                  |
| ----------- | ------------------------------------------------------------------------------------------------------------------ |
| `used`      | Requests you've used in the current quota period.                                                                  |
| `limit`     | Requests available in each quota period. `null` if your plan is unlimited.                                         |
| `available` | Requests you have left in the current quota period. `null` if your plan is unlimited.                              |
| `unlimited` | `true` if your plan has no request limit. When `true`, `limit`, `available` and `expiry` are `null`.               |
| `interval`  | The number of time units in each quota period. For example, `30` with a `timeUnit` of `day` means a 30-day period. |
| `timeUnit`  | `minute`, `hour`, `day`, `week` or `month`.                                                                        |
| `expiry`    | When the quota resets to the limit, in `YYYY-MM-DDTHH:MM:SS.SSSZ` format. `null` if your plan is unlimited.        |

> **Note**
>
> On free plans, `limit` can come back as a string (for example `"1000"`) instead of an integer. Parse it as a number before you compare it.

## Errors

| Status | Meaning                                            | What to do                                                                              |
| ------ | -------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `400`  | Invalid parameters in the request.                 | Check parameter names and values, and URL-encode `userAgent`.                           |
| `401`  | Invalid API key.                                   | Check the key in your `x-api-key` header.                                               |
| `403`  | Your rate plan expired or your quota is exhausted. | Check your quota (see above), or contact your Pixalate account manager about your plan. |
| `5xx`  | The API had an internal error.                     | Contact [support@pixalate.com](mailto:support@pixalate.com).                            |

For limits and errors across all Pixalate APIs, see [Quotas, limits and errors](/apis/quotas-and-errors).

## Related

#### [Risk types and codes](/apis/fraud-api-risk-types)

What each four-digit code in `riskTypes` means.

#### [Fraud API v3 reference](/api-reference/fraud/get-fraud)

Full parameter and response schema.

#### [Migrate from v2 to v3](/apis/fraud-api-v2-to-v3)

What changed and how to switch.

#### [Fraud API v2 reference (legacy)](/api-reference/fraud-v2/get-fraud)

The previous version, still available.