Skip to navigation
APIsFraud API

Migrate from v2 to v3

Move your Fraud API integration to v3 to get risk type codes with every flagged lookup.

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

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.
  • The error codes are the same: 400, 401, 403 and 5xx.

What changed

Areav2v3
Base URLhttps://fraud-api.pixalate.com/api/v2https://fraud-api.pixalate.com/api/v3
Lookup responseprobabilityprobability and riskTypes
riskTypesNot returnedArray of four-digit risk type codes, or null
Whitelisted valuesNot documentedprobability is -1
Quota metadata (no lookup values sent)Nested quota object, plus database.lastUpdatedFlat object: used, limit, available, unlimited, interval, timeUnit, expiry

riskTypes

v3 adds riskTypes to the lookup response:

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

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.

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

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 before you switch.

Switch to v3

1

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.

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

Read riskTypes

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

3

Handle -1

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

4

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.

5

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.