Dashboard API

Call our Dashboard API to get your FraudStop Dashboard data and visualise it in any way you want.

Implementing the Dashboard API

To access the API you need to inform us of your interest. We will provide you with a unique API Key, which you can use to authenticate your requests. To fetch your dashboard data send a POST request to https://fraudstop.empello.net/dash/export/traffic/, with the following fields:

Field	Value	Required
start_day	from date in 'YYYY-MM-DD' format	Required
end_day	to date in 'YYYY-MM-DD' format	Required
country	ISO 2 letter country code (eg gb, fr, cl)	Required
carrier	MCC-MNC Code separated by a hyphen (see here)	Required
service	Service name exactly as presented in the Dashboard	Optional

Note

Authenticate the request using the X-API-KEY value in the request header.

The API will respond with:

Field	Value
success	Boolean value, if false then an error has occurred
status	HTTP status. e.g. 200 for a success
message	error message output (returned when success is false)
data	array of daily data (returned when success is true)

See the following example cURL request and JSON response:

    curl -X POST \
    'https://fraudstop.empello.net/dash/export/traffic/' \
    -H 'x-api-key: myuniqueapikey' \
    -H 'Content-Type: application/json' \
    -d '{
      "start_day": "2023-10-23",
      "end_day": "2023-10-24",
      "country": "pe",
      "carrier": "716-07",
      "service": "My Service"
      }'

Example of successful response:

{
  "success": true,
  "status": 200,
  "data": [ { ... } ] // Array of Objects
}

Example of failed response:

{
  "success": false,
  "status": 409,
  "message": "Incorrect or missing carrier."
}

Returned Data Object

Key	Description
day	The date in 'YYYY-MM-DD' format String
service	The service object. Object
total_visits	The total number of visits. Number
app_visits	The number of in-app visits. Number
web_visits	The number of browser visits. Number
total_clicks	The total number of clicks. Number
app_clicks	The number of in-app clicks. Number
web_clicks	The number of browser clicks. Number
fraudulent_clicks	The total number of blocked clicks. Number
br_app_not_gplay	The number of blocked clicks for reason: App Not on Google Play Number
br_app_spoofing	The number of blocked clicks for reason: App Spoofing Behaviour Number
br_browser_spoofing	The number of blocked clicks for reason: Browser Spoofing Behaviour Number
br_datapoint_missing	The number of blocked clicks for reason: Data Point Missing Number
br_expired_token	The number of blocked clicks for reason: Expired Token Number
br_frequency_device	The number of blocked clicks for reason: Device Frequency Number
br_frequency_ip	The number of blocked clicks for reason: IP Frequency Number
br_frequency_msisdn	The number of blocked clicks for reason: MSISDN Frequency/Injection Number
br_fscan_blocklisted	The number of blocked clicks for reason: FraudScan Blocklisted Number
br_in_iframe	The number of blocked clicks for reason: iFraming Detected Number
br_operator_rule	The number of blocked clicks for reason: Operator Rule Number
br_server_traffic	The number of blocked clicks for reason: Server Traffic Number
br_susp_behaviour	The number of blocked clicks for reason: Suspicious Behaviour Number
br_token_repeated	The number of blocked clicks for reason: Repeat Token Number
br_wrong_country	The number of blocked clicks for reason: Incorrect Country Number
br_wrong_timezone	The number of blocked clicks for reason: Incorrect Timezone Number

Service Object

A single service object consists of:

Key	Description
name	The service name as registered in the FraudStop Dashboard String
serviceId	A unique service Identifier as registered in the FraudStop Dashboard Number
apiVersion	The API version under which the service traffic is implemented Number

Example of returned Data Object:

  {
    "day": "2023-10-23",
    "service": {
      "name": "My Service",
      "serviceId": 999,
      "apiVersion": 1
    },
    "total_visits": 41195,
    "app_visits": 1, // only returned when service runs on APIv2
    "web_visits": 41194, // only returned when service runs on APIv2
    "total_clicks": 7377,
    "app_clicks": 0,
    "web_clicks": 7377,
    "fraudulent_clicks": 7367,
    "br_app_not_gplay": 0,
    "br_app_spoofing": 1432,
    "br_browser_spoofing": 7342,
    "br_datapoint_missing": 7028,
    "br_expired_token": 0,
    "br_frequency_device": 0,
    "br_frequency_ip": 0,
    "br_frequency_msisdn": 0,
    "br_fscan_blocklisted": 0,
    "br_in_iframe": 0,
    "br_server_traffic": 4489,
    "br_susp_behaviour": 0,
    "br_operator_rule": 0,
    "br_token_repeated": 0,
    "br_wrong_country": 6362,
    "br_wrong_timezone": 7342
  },

Blocked Reasons Descriptions

Use the table below to match the returned block reasons with the FraudStop Dashboard labels and descriptions.

Key	Label	Description
br_app_not_gplay	App Not on Google Play	App has been removed from Google Play or is only found in 3rd party app stores.
br_app_spoofing	App Spoofing Behaviour	App traffic spoofing another app or scrubbing their app name.
br_browser_spoofing	Browser Spoofing Behaviour	Browser behaviour does not match the browsers user-agent.
br_datapoint_missing	Data Point Missing	Important data points were not received by us, due to fraud or poor internet connection.
br_expired_token	Expired Token	A token has been submitted that is older than 15 minutes.
br_frequency_device	Device Frequency	This device type makes up too large a percentage of the traffic.
br_frequency_ip	IP Frequency	This IP has subscribed or attempted to subscribe too many times recently.
br_frequency_msisdn	MSISDN Frequency/Injection	This MSISDN has subscribed or attempted to subscribe too many times recently, or MSISDN has been injected.
br_fscan_blocklisted	FraudScan Blocklisted	App has been found performing auto subscriptions through our FraudScan programme.
br_in_iframe	iFraming Detected	The payment script is within an iFrame without authorisation.
br_operator_rule	Operator Rule	A rule mandated by the operator.
br_server_traffic	Server Traffic	Traffic most likely originates from a server.
br_susp_behaviour	Suspicious Behaviour	Evidence of attempted circumvention or interference with the FraudStop script.
br_token_repeated	Repeat Token	A token has been submitted more than once, most likely an implementation issue.
br_wrong_country	Incorrect Country	Detected country does not match the merchant country.
br_wrong_timezone	Incorrect Timezone	Timezone of the device does not match the timezone of the merchant country.