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

# Migrate from v2 to v3

> What changed between Pixalate Fraud API v2 and v3, and the steps to switch your integration.

Fraud API v3 (released October 14, 2026) returns risk type codes next to the fraud probability, so you can see why an IP address, device ID or user agent is flagged and block by risk type. v2 returns the probability only.

v2 remains available as a legacy API. You don't need to do anything if you stay on v2. The v2 reference is at [Fraud API v2 (legacy)](/api-reference/fraud-v2/get-fraud).

## What stays the same

* The endpoint is still `GET /fraud` on `fraud-api.pixalate.com`.
* You authenticate the same way, with your API key in the `x-api-key` header.
* The query parameters are the same: `ip`, `deviceId`, `userAgent` and `pretty`.
* `probability` is still in the response, and Pixalate's threshold guidance is unchanged. See [Decide when to block](/apis/fraud-api#decide-when-to-block).
* The error codes are the same: `400`, `401`, `403` and `5xx`.

## What changed

| Area                                   | v2                                                 | v3                                                                                       |
| -------------------------------------- | -------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| Base URL                               | `https://fraud-api.pixalate.com/api/v2`            | `https://fraud-api.pixalate.com/api/v3`                                                  |
| Lookup response                        | `probability`                                      | `probability` and `riskTypes`                                                            |
| `riskTypes`                            | Not returned                                       | Array of four-digit risk type codes, or `null`                                           |
| Whitelisted values                     | Not documented                                     | `probability` is `-1`                                                                    |
| Quota metadata (no lookup values sent) | Nested `quota` object, plus `database.lastUpdated` | Flat object: `used`, `limit`, `available`, `unlimited`, `interval`, `timeUnit`, `expiry` |

### riskTypes

v3 adds `riskTypes` to the lookup response:

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

* It lists the four-digit codes associated with the values you sent during the look-back period. It can contain more than one code.
* It's `null` when `probability` is `0` or `-1`, or when a value is flagged but no risk type is available for it. It's never an empty array.

To decode the codes, see [Risk types and codes](/apis/fraud-api-risk-types).

### Quota metadata

When you call the endpoint without `ip`, `deviceId` or `userAgent`, both versions return your quota instead of a lookup, but the shape is different.

#### v2

```json
{
  "database": { "lastUpdated": "2022-04-30" },
  "quota": {
    "available": 480,
    "used": 520,
    "expiry": "2022-05-01T12:45:23.234Z",
    "limit": 1000,
    "interval": 1000,
    "timeUnit": "month"
  }
}
```

#### v3

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

In v3, `unlimited` is `true` when your plan has no request limit, and then `limit`, `available` and `expiry` are `null`. v3 doesn't return `database.lastUpdated`.

### Device ID types

The v3 reference lists these `deviceId` types: ADID, IDFA, RIDA, MSAI, WAID, and MD5 or SHA-1 hashes of a hardware device identifier. The v2 reference also listed IDFV (Apple's Identifier for Vendor). If you send IDFVs today, contact [support@pixalate.com](mailto:support@pixalate.com) before you switch.

## Switch to v3

#### Change the base URL

Replace `https://fraud-api.pixalate.com/api/v2` with `https://fraud-api.pixalate.com/api/v3`. Keep the same path, parameters and `x-api-key` header.

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

#### Read riskTypes

Parse `riskTypes` as a nullable array of integers. Treat `null` as "no codes", not as "not flagged", and keep checking `probability`.

#### Handle -1

If your code assumes `probability` is never negative, handle `-1`, which means the value is whitelisted by Pixalate. Don't block it.

#### Update quota parsing

If you read quota metadata, move from `quota.available`, `quota.used` and so on to the top-level v3 fields, and handle `unlimited` and `null` values. Remove any use of `database.lastUpdated`.

#### Add risk type rules (optional)

Block on a class (`2xxx`), a category (`25xx`) or a single type (`2502`), on its own or together with a probability threshold. See [Block by class, category or type](/apis/fraud-api-risk-types#block-by-class-category-or-type).

## Related

* [Fraud API guide](/apis/fraud-api)
* [Risk types and codes](/apis/fraud-api-risk-types)
* [Fraud API v3 reference](/api-reference/fraud/get-fraud)
* [Fraud API v2 reference (legacy)](/api-reference/fraud-v2/get-fraud)