Introduction

Welcome to the Fraudshield API.

SDK

We provide an official SDK for PHP. If you wish to use a different language you can follow the examples below in order to consume the API in your favorite language.

Authentications

Fraudshield API requires each request to be authenticated. All what you need to do is include your user ID, and your API token with each request. You can find both in the settings page.

<?php
use Fraudshield\Fraudshield;

$fs = new Fraudshield(USER_ID, API_TOKEN);

Make sure to replace USER_ID and API_TOKEN with your user ID and your API Token.

Query Parameters

Parameter	Type	Description
user_id	string	the user ID
api_token	string	the API token

Timezones

Our API requires passing a timezone for many of its endpoints. you can find the list of supported timezones here.

Example

If you live for instance in Berlin, and you want to get all your reports according to you local time, you can use Europe/Berlin as a timezone with you API requests.

Reports

Conversion report

<?php
use Fraudshield\Fraudshield;
use Fraudshield\Reports\ConversionReport;

$fs = new Fraudshield(USER_ID, API_TOKEN);

$report = new ConversionReport(81,'2017-06-05', '2017-06-05');
var_dump($fs->getReport($report));

The above command returns JSON structured like this:

{
    "total": 2691,
    "per_page": "50",
    "current_page": 1,
    "last_page": 54,
    "next_page_url": "/?page=2",
    "prev_page_url": null,
    "from": 1,
    "to": 50,
    "data": [
        {
            "_index": "fraudshield-2017-06-01",
            "_type": "conversion",
            "_id": "AVxhl1FBViLK0owKju6d",
            "_score": null,
            "_source": {
                "tracker_id": 81,
                "affiliate": "Affiliate_229",
                "sub_id": null,
                "product": "Product_4",
                "partner": "Partner_45",
                "fingerprint": "95267744",
                "requesNote — When using the SDK you can skip using all the mandatory parameters. The skipped parameters would be set to some default values. t_time": "17:50:31",
                "session_time": "0D, 00:06:46",
                "session_time_in_seconds": 406,
                "type": "conversion",
                "status": "approved",
                "http_user_agent": "Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/28.0.1500.75 Safari/537.36 MRCHROME",
                "os": "Windows 7",
                "browser": "Mail.ru Chromium Browser 28.0.1500",
                "device": "Other",
                "http_referer": "http://www.referer_1558.com",
                "http_click_referer": "http://www.clr.referer_1558.com",
                "score": 0,
                "server_ip": null,
                "id": "FS_592f82f05cbf10.21652871",
                "rejected_reason": {
                    "rejected_reason_id": "",
                    "simple_reason": "",
                    "advanced_reason": ""
                },
                "isp": "TNS-Plus LLP",
                "host": "185.8.234.55",
                "country_code": "KZ",
                "city": null,
                "reasons": [
                    {
                        "filter_id": {
                            "rejected_reason_id": 2,
                            "simple_reason": "GEO Mismatch",
                            "advanced_reason": "Country Mismatch"
                        },
                        "priority": 500,
                        "matches": 0,
                        "limit": "[\"DE\",\"RU\",\"PL\",\"KG\",\"BY\",\"PT\",\"UY\",\"UA\",\"US\",\"KZ\",\"FR\",\"ES\",\"DK\",\"AM\",\"SK\",\"CH\",\"IT\",\"BR\",\"GR\",\"EE\",\"CA\",\"VN\",\"MD\",\"EG\",\"LT\",\"AR\"]",
                        "ratio": 0,
                        "weight": "100.00",
                        "weighted_ratio": 0
                    },
                    {
                        "filter_id": {
                            "rejected_reason_id": 4,
                            "simple_reason": "IP Pattern",
                            "advanced_reason": "IP Pattern"
                        },
                        "priority": 100,
                        "matches": 0,
                        "limit": "2",
                        "ratio": 0,
                        "weight": "40.00",
                        "weighted_ratio": 0
                    }
                ],
                "extra_parameters": [
                    {
                        "param_name": "country_code",
                        "param_value": "KZ"
                    },
                    {
                        "param_name": "fs_id",
                        "param_value": "32"
                    },
                    {
                        "param_name": "aip",
                        "param_value": "M7b19a3c2b23cdd7779a3a5b832b019c"
                    },
                    {
                        "param_name": "aid",
                        "param_value": "j7b19a3c2b23cdd7779a3a5b832b019c"
                    },
                    {
                        "param_name": "is_api_insert",
                        "param_value": "1"
                    },
                    {
                        "param_name": "fs_live_filtration",
                        "param_value": "1"
                    },
                    {
                        "param_name": "fs_sync",
                        "param_value": "1"
                    }
                ],
                "remote_address": "185.8.234.55",
                "uuid": null,
                "device_id": null,
                "request_date": "2017-06-01",
                "risk": "No Risk",
                "consolidated_affiliate": "Affiliate_229",
                "affiliate_label": "N/A",
                "partner_label": "N/A",
                "product_label": "N/A"
            },
            "sort": [
                1496339431000
            ]
        },
...
}

This endpoint retrieves the Conversion report.

HTTP Request

GET https://fraudshield.24metrics.com/api/v1/reports/conversion.json

Query Parameters

Parameter	Type	Description	Notes
tracker_id	integer	the tracker ID of the report you want to get.	Mandatory
date_start	yyyy-mm-dd	the start date of the report.	Mandatory
date_end	yyyy-mm-dd	the end date of the report.	Mandatory
timezone	string	the timezone of the report.	Mandatory
goal	Boolean	set to true in order to include goals in the report .	Optional
click	Boolean	set to true in order to include clicks in the report.	optional

Filters

You can also apply some filters to the reports. the filters should be added in a json format. for instance if we want to filter by the country_code “FR” we should do it as follow:

search_fields[]={"term":"country_code","query":"FR"}

here is the list of the availible filters:

• http_click_referer
• country_code
• remote_address
• product
• affiliate
• partner
• sub_id
• status
• rejected_reason.simple_reason
• rejected_reason.advanced_reason
• min_score
• max_score

Pagination (mandatory)

The conversion report requires pagination, you can use it by sending these parameters with the request:

Parameter	type	Description
count	integer	the number of results per page.
page	integer	the index of the page.

Conversion Scroll report

<?php
use Fraudshield\Fraudshield;
use Fraudshield\Reports\ConversionScrollReport;

$fs = new Fraudshield(USER_ID, API_TOKEN);

$report = new ConversionScrollReport(81,'2017-06-05', '2017-06-05');
$report->setNextPageId('cXVlcnlUaGVuRmV0Y2g7Mzs1OTQ6OG9XN0hOZ3lSZlNXeC1meUEtaHozUTs1OTU6OG9XN0hOZ3lSZlNXeC1meUEtaHozUTs1OTY6OG9XN0hOZ3lSZlNXeC1meUEtaHozUTswOw=='); 
// no need to set `next_page_id` with the first request, you'd need it starting from the second request
var_dump($fs->getReport($report));

The above command returns JSON structured like this:

{
    {
    "next_page_url": "https://fraudshield.24metrics.com/api/v1/reports/conversion_scroll.json?api_token=Ia1u9NIzFGML7DmxNqFZUE8p3CRqcZseMztqCVme2ghkDQHUvCv32bHCeOeQ&click=0&count=10&date_end=2017-08-01&date_start=2017-08-01&goal=0&page=1&timezone=UTC&tracker_id=1&user_id=1&next_page_id=cXVlcnlUaGVuRmV0Y2g7Mzs1OTQ6OG9XN0hOZ3lSZlNXeC1meUEtaHozUTs1OTU6OG9XN0hOZ3lSZlNXeC1meUEtaHozUTs1OTY6OG9XN0hOZ3lSZlNXeC1meUEtaHozUTswOw==",
    "data": [
        {
            "affiliate": "Affiliate_1",
            "sub_id": "Sub_2",
            "product": "Product_1",
            "partner": "Partner_1",
            "fingerprint": "2415426325",
            "request_time": "16:50:55",
            "session_time_in_seconds": 147,
            "type": "conversion",
            "remote_address": "89.178.237.140",
            "server_ip": "127.0.0.1",
            "http_user_agent": "Mozilla/5.0 (Windows NT 6.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/38.0.2125.111 Safari/537.36",
            "http_referer": "http://www.referer_1563.com",
            "http_click_referer": "http://www.clr.referer_1563.com",
            "tracker_id": "1",
            "id": "fs_598308da5d09b1.55404672",
            "extra_parameters": [
                {
                    "param_name": "ext",
                    "param_value": "json"
                }
            ],
            "country_code": "RU",
            "city": "TestCity3",
            "os": "Windows 7",
            "isp": "BT Public Internet Service",
            "browser": "",
            "device": "Other",
            "status": "rejected",
            "request_date": "2017-08-01",
            "session_time": "0D, 00:02:27",
            "risk": "No Risk",
            "consolidated_affiliate": "Affiliate_1",
            "reason": "IP Pattern",
            "advanced_reason": "IP Pattern",
            "affiliate_label": "Affiliate 1 Label",
            "partner_label": "Partner 1 Label",
            "product_label": "Product 1 Label"
        },
        {
            "affiliate": "Affiliate_2",
            "sub_id": "Sub_2",
            "product": "Product_1",
            "partner": null,
            "fingerprint": "867620924",
            "request_time": "16:48:53",
            "session_time_in_seconds": 270,
            "type": "conversion",
            "remote_address": "93.197.127.135",
            "server_ip": "127.0.0.1",
            "http_user_agent": "Mozilla/5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/38.0.2125.111 Safari/537.36",
            "http_referer": "http://www.referer_1552.com",
            "http_click_referer": "http://www.clr.referer_1552.com",
            "tracker_id": "1",
            "id": "fs_598308da560a82.36904939",
            "extra_parameters": [
                {
                    "param_name": "ext",
                    "param_value": "json"
                }
            ],
            "country_code": "DE",
            "city": "TestCity2",
            "os": "Windows 8.1",
            "isp": "Verizon Wireless",
            "browser": "",
            "device": "Other",
            "status": "rejected",
            "request_date": "2017-08-01",
            "session_time": "0D, 00:04:30",
            "risk": "No Risk",
            "consolidated_affiliate": "Affiliate_2",
            "reason": "Abnormal Device Distribution",
            "advanced_reason": "Excessive old devices - android",
            "affiliate_label": "Affiliate 2 Label",
            "partner_label": "N/A",
            "product_label": "Product 1 Label"
        },
...
}

This endpoint retrieves the Conversion report using the scroll API.

HTTP Request

POST https://fraudshield.24metrics.com/api/v1/reports/conversion_scroll.json

Fraud report

<?php
use Fraudshield\Reports\ConversionReport;
use Fraudshield\Fraudshield;

$fs = new Fraudshield(USER_ID, API_TOKEN);

// create the report
$report = new ConversionReport(81,'2017-06-05', '2017-06-05');
// add data sources
$report->addDataSource('affiliate')->addDataSource('partner');
// add a filter
$report->addFilter('min_conversions', 50);

// adding a data source and filter by it
$report->addDataSource('sub_id')->addFilter('sub_id', 500); 


var_dump($fs->getReport($report));

The above command returns JSON structured like this:

{
    "fraud": {
        "results": [
            {
                "tracker_id": 81,
                "conversion": 84,
                "approved": 69,
                "rejected": 15,
                "goal": 86,
                "reasons": {
                    "GEO Mismatch": 15
                },
                "approval_rate": 82.14,
                "rejection_rate": 17.86,
                "id": "5937e3e1c89c4",
                "goal_rate": 102.38
            }
        ]
    }
}

This endpoint retrieves the Fraud report.

HTTP Request

GET https://fraudshield.24metrics.com/api/v1/reports/fraud.json

Query Parameters

Parameter	type	Description	Note
tracker_id	integer	the tracker ID of the report you want to get.	Mandatory
date_start	yyyy-mm-dd	the start date of the report.	Mandatory
date_end	yyyy-mm-dd	the end date of the report.	Mandatory
timezone	string	the timezone of the report.	Mandatory
group	array	data sources	Optional
search_fields	array	filters	Optional

Data sources

You can add up to 3 data sources before generating the fraud report: the available sources are:

• sub_id
• partner
• affiliate
• product
• goal

Filters

You can also apply some filters to the reports. the filters should be added in a json format. for instance if we want to filter by a minimum rejection rate of 10 percent we should do it as follow:

search_fields[]={"term":"min_conversions","query":50}

Filters Parameters

Parameter	type	Description
min_conversions	integer	the minimum conversion
min_rejection_rate	integer	the minimum rejection rate (%)
max_rejection_rate	integer	the maximum rejection rate (%)
min_goals_reached	integer	the minimum percentage of goals reached (%)
max_goals_reached	integer	the maximum percentage of goals reached (%)

Example

Here is an example of a request to get the fraud report from 2017-05-05 to 2017-06-05 for the tracker 81 using two data sources, partner and sub_id

https://fraudshield.24metrics.com/api/v1/reports/fraud.json?tracker_id=81&group[]=sub_id&group[]=partner&date_start=2017-05-05&date_end=2017-06-05&timezone=UTC&user_id=xyz&api_token=YOUR_TOKEN_HERE

if we want to add two filters to this requests (“minimum conversion” and “maximum rejection rate”) we request should look like this:

https://fraudshield.24metrics.com/api/v1/reports/fraud.json?tracker_id=81&group[]=sub_id&group[]=partner&search_fields[]={"term":"min_conversions","query":50}&search_fields[]={"term":"max_rejection_rate","query":30}&date_start=2017-05-05&date_end=2017-06-05&timezone=UTC&user_id=xyz&api_token=YOUR_TOKEN_HERE

Global report

<?php
use Fraudshield\Fraudshield;
use Fraudshield\Reports\GlobalReport;

$fs = new Fraudshield(USER_ID, API_TOKEN);
// create the report
$report = new GlobalReport('2017-05-05', '2017-06-05');

// add data sources
$report->addDataSource('affiliate')->addDataSource('partner');
// add a filter
$report->addFilter('tracker_id', 81);

// adding a data source and filter by it
$report->addDataSource('country_code')->addFilter('country_code', 'de'); 


var_dump($fs->getReport($report));

The above command returns JSON structured like this:

{
    "results": [
        {
            "tracker_id": 81,
            "click": 28634,
            "goal": 2863,
            "conversion": 2704,
            "approved": 2215,
            "rejected": 489,
            "": 0,
            "tracker": "Demo Integration",
            "conversion_rate": 9.44
        },
        {
            "tracker_id": 698,
            "conversion": 6,
            "click": 0,
            "goal": 0,
            "approved": 3,
            "rejected": 3,
            "": 0,
            "tracker": "testSomething",
            "conversion_rate": "N/A"
        }
    ]
}

This endpoint retrieves the Global report.

HTTP Request

GET https://fraudshield.24metrics.com/api/v1/reports/global.json

Query Parameters

Parameter	type	Description	Note
date_start	yyyy-mm-dd	the start date of the report.	Mandatory
date_end	yyyy-mm-dd	the end date of the report.	Mandatory
timezone	string	the timezone of the report.	Mandatory
group	array	data sources	Mandatory
search_fields	array	filters	Optional

Data sources

You can add up to 4 data sources (including tracker_id that should be always included) before generating the fraud report: the available sources are:

• tracker_id
• affiliate
• partner
• product
• sub_id
• country_code

Filters

You can also apply some filters to the reports. the filters should be added in a json format. for instance if we want to filter by the tracker id 81 we should do it as follow:

search_fields[]={"term":"tracker_id","query":81}

Example

Here is an example of a request to get the global report from 2017-05-05 to 2017-06-05

https://fraudshield.24metrics.com/api/v1/reports/global.json?group[]=tracker_id&date_start=2017-05-05&date_end=2017-06-05&timezone=UTC&user_id=xyz&api_token=YOUR_TOKEN_HERE

here is an example where we filter by a specific tracker: https://fraudshield.24metrics.com/api/v1/reports/global.json?group[]=tracker_id&search_fields[]={"term":"tracker_id","query":81}&date_start=2017-05-05&date_end=2017-06-05&timezone=UTC&user_id=xyz&api_token=YOUR_TOKEN_HERE

Goal report

<?php
use Fraudshield\Fraudshield;
use Fraudshield\Reports\GoalReport;

$fs = new Fraudshield(USER_ID, API_TOKEN);
// create the report
$report = new GoalReport(81,'2017-06-05', '2017-06-05');

// add data sources
$report->addDataSource('affiliate')->addDataSource('partner');
// add a filter
$report->addFilter('min_conversions', 50);

// adding a data source and filter by it
$report->addDataSource('sub_id')->addFilter('sub_id', 500); 


var_dump($fs->getReport($report));

The above command returns JSON structured like this:

{
    "fraud": {
        "results": [
            {
                "tracker_id": 81,
                "conversion": 84,
                "approved": 69,
                "rejected": 15,
                "goal": 86,
                "reasons": {
                    "GEO Mismatch": 15
                },
                "approval_rate": 82.14,
                "rejection_rate": 17.86,
                "id": "5937e3e1c89c4",
                "goal_rate": 102.38
            }
        ]
    }
}

This endpoint retrieves the Fraud report.

HTTP Request

GET https://fraudshield.24metrics.com/api/v1/reports/goal.json

Query Parameters

Parameter	type	Description	Note
tracker_id	integer	the tracker ID of the report you want to get.	Mandatory
date_start	yyyy-mm-dd	the start date of the report.	Mandatory
date_end	yyyy-mm-dd	the end date of the report.	Mandatory
timezone	string	the timezone of the report.	Mandatory
group	array	data sources	Mandatory
search_fields	array	filters	Optional

Data sources

You can add up to 3 data sources before generating the fraud report: the available sources are:

• sub_id
• partner
• affiliate
• product
• goal

Filters

You can also apply some filters to the reports. the filters should be added in a json format. for instance if we want to filter by a minimum rejection rate of 10 percent we should do it as follow:

search_fields[]={"term":"min_conversions","query":50}

Filters Parameters

Parameter	type	Description
min_conversions	integer	the minimum conversion
min_rejection_rate	integer	the minimum rejection rate (%)
max_rejection_rate	integer	the maximum rejection rate (%)
min_goals_reached	integer	the minimum percentage of goals reached (%)
max_goals_reached	integer	the maximum percentage of goals reached (%)

Example

Here is an example of a request to get the fraud report from 2017-05-05 to 2017-06-05 for the tracker 81 using two data sources, partner and sub_id

https://fraudshield.24metrics.com/api/v1/reports/fraud.json?tracker_id=81&group[]=sub_id&group[]=partner&date_start=2017-05-05&date_end=2017-06-05&timezone=UTC&user_id=xyz&api_token=YOUR_TOKEN_HERE

if we want to add two filters to this requests (“minimum conversion” and “maximum rejection rate”) we request should look like this:

https://fraudshield.24metrics.com/api/v1/reports/fraud.json?tracker_id=81&group[]=sub_id&group[]=partner&search_fields[]={"term":"min_conversions","query":50}&search_fields[]={"term":"max_rejection_rate","query":30}&date_start=2017-05-05&date_end=2017-06-05&timezone=UTC&user_id=xyz&api_token=YOUR_TOKEN_HERE

Interval report

<?php
use Fraudshield\Reports\IntervalReport;
use Fraudshield\Fraudshield;

$fs = new Fraudshield(USER_ID, API_TOKEN);
// create the report
$report = new IntervalReport('2017-06-05', '2017-06-05');

// add data sources
$report->addDataSource('affiliate');

// adding a data source and filter by it
$report->addDataSource('sub_id')->addFilter('sub_id', 500); 


var_dump($fs->getReport($report));

The above command returns JSON structured like this:

{
    "results": [
    {
        "intervals": "2017-05-05T00:00:00+0000",
        "click": 970,
        "goal": 97,
        "conversion": 22,
        "approved": 19,
        "rejected": 3,
        "conversion_rate": 2.27,
        "rejection_rate": 13.64
    },
    {
        "intervals": "2017-05-06T00:00:00+0000",
        "click": 990,
        "goal": 99,
        "conversion": 26,
        "approved": 22,
        "rejected": 4,
        "conversion_rate": 2.63,
        "rejection_rate": 15.38
    },
    {
        "intervals": "2017-05-07T00:00:00+0000",
        "click": 754,
        "goal": 75,
        "conversion": 72,
        "approved": 56,
        "rejected": 16,
        "conversion_rate": 9.55,
        "rejection_rate": 22.22
    },
    {
        "intervals": "2017-05-08T00:00:00+0000",
        "click": 910,
        "conversion": 96,
        "goal": 91,
        "approved": 63,
        "rejected": 33,
        "conversion_rate": 10.55,
        "rejection_rate": 34.38
    },

This endpoint retrieves the Interval report.

HTTP Request

GET https://fraudshield.24metrics.com/api/v1/reports/interval.json

Query Parameters

Parameter	type	Description	Note
date_start	yyyy-mm-dd	the start date of the report.	Mandatory
date_end	yyyy-mm-dd	the end date of the report.	Mandatory
timezone	string	the timezone of the report.	Mandatory
group	array	data sources	mandatory
time_interval	array	the time interval used in the report	mandatory
chart_type	string	the type of the chart to return	it should always equals to conversion_rate

Data sources

You can add up to 3 data sources before generating the fraud report: the available sources are:

• tracker_id
• affiliate
• partner
• product
• sub_id

you should always include the tracker_id with every request

Filters

You can also apply some filters to the reports. the filters should be added in a json format. for instance if we want to filter by a tracker_id 81 we should do it as follow:

search_fields[]={"term":"tracker_id","query":81}

there are no specific filters for the interval report. you have to add data sources in order to filter by them.

Time intervals

here are the availible time intervals:

• hour
• day
• week
• month
• year

Example

Here is an example of a request to get the interval report from 2017-05-05 to 2017-06-05 with an interval of week:

https://fraudshield.24metrics.com/api/v1/reports/interval.json?chart_type=conversion_rate&count=25&page=1&time_interval=week&group[]=tracker_id&date_start=2017-05-05&date_end=2017-06-05&timezone=UTC&user_id=xyz&api_token=YOUR_TOKEN_HERE

Entry report

<?php
use Fraudshield\Fraudshield;
use Fraudshield\Reports\EntryReport;

$fs = new Fraudshield(USER_ID, API_TOKEN);

$report = new EntryReport('conversion', 'FS_59412b282a0150.92227388');
var_dump($fs->getReport($report));

The above command returns JSON structured like this:

[
    {
        "tracker_id": 8,
        "affiliate": null,
        "sub_id": null,
        "product": null,
        "partner": null,
        "request_time": "2017-06-14T12:25:12+00:00",
        "session_time": "00:00:00",
        "session_time_in_seconds": 0,
        "type": "conversion",
        "status": "approved",
        "http_user_agent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/58.0.3029.110 Safari/537.36",
        "os": "Linux",
        "browser": "Chrome 58.0.3029",
        "device": "Other",
        "http_referer": "",
        "http_click_referer": "",
        "server_ip": null,
        "id": "FS_59412b282a0150.92227388",
        "isp": "This parameter is unavailable in selected .BIN data file. Please upgrade.",
        "host": "192.168.56.1",
        "country_code": null,
        "city": null,
        "extra_parameters": [
            {
                "param_name": "queued_insert_id",
                "param_value": "job_id_59412b282a00e8.82357788"
            }
        ],
        "remote_address": "192.168.56.1",
        "uuid": null,
        "device_id": null,
        "risk": "No Risk",
        "reason": "",
        "advanced_reason": "",
        "rejected_reason": "",
        "affiliate_label": "N/A",
        "partner_label": "N/A",
        "product_label": "N/A"
    }
]

This endpoint retrieves the Entry report.

HTTP Request

GET https://fraudshield.24metrics.com/api/v1/reports/{entry_type}/{entry_id}

Query Parameters

Parameter	Type	Description	Notes
entry_type	string	the type of the entry (eg: converions, goal).	Mandatory
entry_id	string	the ID of the entry.	Mandatory