Ad Fraud API v2.0.1

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:

https://fraud-api.pixalate.com/api/v2

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://fraud-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://fraud-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://fraud-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://fraud-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://fraud-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://fraud-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

Type

Required

Description

pretty

query

boolean

false

If true, return pretty JSON. Default is false.

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:

ID Type Name	Operating System	ID Length	Description	Example
ADID	Android	36	Google advertising ID	FF67345D-BF11-7823-1111-FFED421776FC
IDFA	iOS	36	Apple advertising ID	A217D9FC-C1BE-4BEF-94CD-1EE82147C1AA
MD5	Multiple	32	The MD5 hash of a hardware device identifier (e.g. MAC address, IMEI, or advertising ID).	d9527b5207097c5770ca448322489426
SHA1	Multiple	40	The SHA-1 hash of a hardware device identifier (e.g. MAC address, IMEI, or advertising ID).	2971074629cc8f33146c5eb08b39f157da5ce356
WAID	Windows	36	Windows advertising ID	97615775-57b5-4300-90b4-ba0c22b60e34
RIDA	Roku OS	36	Roku’s privacy-friendly device ID	331319d2-4cc2-51ac-de21-aa62f1e143c1
MSAI	Xbox	36	Advertising ID for Microsoft's Xbox	bc23c3de-5d32-4d0c-de3a-94ce878a0379

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.

Ad Fraud API

Enrichment API

SCO Validation & Verification API

Getting Started

Enrichment API

Ad Fraud API

SCO Validation & Verification API

Video Tutorials

API Documentation

Ad Fraud API v2.0.1

Authentication

Fraud

Get Fraud

Parameters

Responses

Response Schema

Enumerated Values

Schemas

Metadata

Properties

Enumerated Values

FraudInfo

Properties