NAV Navbar
Logo
php

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 = ConversionReport(81,'2017-06-05', '2017-06-05');
var_dump($fsgetReport($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:

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 = ConversionScrollReport(81,'2017-06-05', '2017-06-05');
var_dump($fsgetReport($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

GET 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 = 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:

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 = 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:

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 = 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:

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 = 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:

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:

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 = EntryReport('conversion', 'FS_59412b282a0150.92227388');
var_dump($fsgetReport($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
php