Ad Fraud API v2.0.0
Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.
The Fraud API is a service which allows subscribers to request Pixalate's servers to retrieve the probability (risk score) and determine if a user's IP, DeviceID or User-Agent is compromised or performing malicious activity. Any fields included in the response, but not documented herein are subject to change without notice.
Base URLs:
Email: Pixalate, Inc. Web: Pixalate, Inc.
Authentication
- API Key (ApiKey)
- Parameter Name: x-api-key, in: header. Authentication and authorization are achieved by supplying your Pixalate provided API key in the request's header. An API key may be obtained by signing up for an account on the Pixalate developer website.
Fraud
Get Fraud
Code samples
# You can also use wget
curl -X GET https://api.pixalate.com/api/v2/fraud \
-H 'Accept: application/json' \
-H 'x-api-key: API_KEY'
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Net.Http.Headers;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;
/// <<summary>>
/// Example of Http Client
/// <</summary>>
public class HttpExample
{
private HttpClient Client { get; set; }
/// <<summary>>
/// Setup http client
/// <</summary>>
public HttpExample()
{
Client = new HttpClient();
}
/// Make a dummy request
public async Task MakeGetRequest()
{
string url = "https://api.pixalate.com/api/v2/fraud";
var result = await GetAsync(url);
}
/// Performs a GET Request
public async Task GetAsync(string url)
{
//Start the request
HttpResponseMessage response = await Client.GetAsync(url);
//Validate result
response.EnsureSuccessStatusCode();
}
/// Deserialize object from request response
private async Task DeserializeObject(HttpResponseMessage response)
{
//Read body
string responseBody = await response.Content.ReadAsStringAsync();
//Deserialize Body to object
var result = JsonConvert.DeserializeObject(responseBody);
}
}
package main
import (
"bytes"
"net/http"
)
func main() {
headers := map[string][]string{
"Accept": []string{"application/json"},
"x-api-key": []string{"API_KEY"},
}
data := bytes.NewBuffer([]byte{jsonReq})
req, err := http.NewRequest("GET", "https://api.pixalate.com/api/v2/fraud", data)
req.Header = headers
client := &http.Client{}
resp, err := client.Do(req)
// ...
}
const headers = {
'Accept':'application/json',
'x-api-key':'API_KEY'
};
fetch('https://api.pixalate.com/api/v2/fraud',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
const fetch = require('node-fetch');
const headers = {
'Accept':'application/json',
'x-api-key':'API_KEY'
};
fetch('https://api.pixalate.com/api/v2/fraud',
{
method: 'GET',
headers: headers
})
.then(function(res) {
return res.json();
}).then(function(body) {
console.log(body);
});
import requests
headers = {
'Accept': 'application/json',
'x-api-key': 'API_KEY'
}
r = requests.get('https://api.pixalate.com/api/v2/fraud', headers = headers)
print(r.json())
GET /fraud
Retrieve probability of fraud for a specific IP, Device, or Agent. The Fraud Blocking API returns a probability (risk score) 0.01 to 1.0 representing the likelihood a given value is related to malicious or compromised devices. This risk scoring is calculated by Pixalate’s proprietary machine-learning algorithm and allows clients to set their own blocking thresholds based on the quality and scale of their supply inventory. The following is a general guideline for setting fraud blocking thresholds:
- Probability equal to 1.0, for filtering out only the worst offender for blocking (deterministic).
- Probability is greater than or equal to 0.90 for filtering out users that are fraudulent beyond a reasonable doubt.
- Probability between 0.75 (inclusive) and 0.90 (exclusive) to filter out users associated with clear and convincing evidence that they are fraudulent.
- Probability between 0.5 (inclusive) and 0.75 (exclusive) to filter out users that it is more likely than not that they are fraudulent (also known as preponderance of the evidence standard).
Pixalate does not recommend blocking any probabilities less than 0.5. When making adjustments to the probability threshold, Pixalate highly recommends regular checks and balances against impression delivery as lowering the probabilistic threshold can potentially impact the impression count.
Zero or more of the following parameters may be provided. If more than one parameter is specified, the probability returned is determined by assessing risk based on the combination of each parameter’s individual risk probability.
Not specifying an IP, Device, or Agent will return the metadata for fraud, including the user's current quota. See alternate response schema below.
Parameters
| Name | In | Type | Required | Description | ||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| pretty | query | boolean | false | If true, return pretty JSON. Default is false. | ||||||||||||||||||||||||||||||||||||||||
| ip | query | string | false | The internet protocol address. | ||||||||||||||||||||||||||||||||||||||||
| deviceId | query | string | false | An ID that characterizes a mobile device. This is the actual mobile identifier. Various types are acceptable as follows:
|
||||||||||||||||||||||||||||||||||||||||
| userAgent | query | string | false | The browser or device supplied agent string. |
Example responses
200 Response
{
"probability": 0.6
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | OK | Inline |
| 400 | Bad Request | Bad Request - Invalid parameters in request. | None |
| 401 | Unauthorized | Unauthorized - Invalid API Key. | None |
| 403 | Forbidden | Forbidden - Rate plan expired or quota has been exhausted. | None |
| 5XX | Unknown | Server Error - The API experienced an internal error. Contact support. | None |
Response Schema
Enumerated Values
| Property | Value |
|---|---|
| timeUnit | minute |
| timeUnit | hour |
| timeUnit | day |
| timeUnit | week |
| timeUnit | month |
Schemas
Metadata
{
"database": {
"lastUpdated": "2022-04-30"
},
"quota": {
"available": 480,
"used": 520,
"expiry": "2022-05-01T12:45:23.234Z",
"limit": 1000,
"interval": 1000,
"timeUnit": "month"
}
}
Fraud metadata information.
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| database | object | false | none | The Fraud database state information. |
| » lastUpdated | string(date) | false | none | The date when the Fraud database was last updated. The date format is YYYY-MM-DD. |
| quota | object | false | none | Quota state information. |
| » available | integer | false | none | The amount of quota available for use. |
| » used | integer | false | none | The amount of quota used. |
| » expiry | string(date) | false | none | The datetime when the quota will be refreshed back to the limit. The datetime format is YYYY-MM-DDTHH:MM:SS.SSSZ. |
| » limit | integer | false | none | The amount of quota to be made available for use when the quota is refreshed. |
| » interval | integer | false | none | The number of time units used in calculating the quota refresh datetime. |
| » timeUnit | string | false | none | The time unit used in calculating the quota refresh datetime. |
Enumerated Values
| Property | Value |
|---|---|
| timeUnit | minute |
| timeUnit | hour |
| timeUnit | day |
| timeUnit | week |
| timeUnit | month |
FraudInfo
{
"probability": 0.6
}
Fraud information
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| probability | number | false | none | The probability of fraud (0.1 through 1.0). 0.0 indicates unknown. |