Data API

For retrieving data from the FraudScore system, you can use our Data API.

Data API allows you to obtain all data slices that can be configured in reports via the web interface, and even more.

Specifications

In the left sidebar, within the submenu of each integration, you have access to the API Documentation section.

In this section, you can find the CHANNEL_ID of your integration and your personal USER_KEY. Additionally, this section provides a link to the interactive Data API documentation, where you can explore its capabilities and perform test requests.

The format of the link to the interactive documentation:

https://api.fraudscore.ai/<CHANNEL_ID>/help?key=<USER_KEY>

Simply insert your CHANNEL_ID and USER_KEY.

Request Examples

Events ListEvents Grouping

Download the file events_list.py or review the code below:

events_list.py

#!/usr/bin/env python3
# coding: utf8

# Events List Request Example

import json
import requests

# Your channel id.

CHANNEL = 'channel_id'

# Your user key.

USER_KEY = 'user_key'

# Event type.
# Possible values:
# install, click, impression, custom.

EVENT = 'install'

# This is how URL looks like.

url = f'https://get.fraudscore.ai/{CHANNEL}/{EVENT}'

# Initialize request parameters.
# User key required.

params = dict(key = USER_KEY)

# List of fields we need.
# String or list of strings.

params['field'] = ['datetime', 'offer_id', 'affiliate_id', 'ipv4_str', 'ua']

# Optional filter expression.
# String (JSON).
# Expression format: ["operator", operand, operand, ...]
# Operand format: ["field", "value"]
# Nested expressions are supported. Example:
# `date >= "2024-01-01" AND date <= "2024-06-01" AND (offer_id = "id1" OR offer_id = "id2")`

params['filter'] = json.dumps([
    "AND",
    ["date_ge", "2024-01-01"],
    ["date_le", "2024-06-01"],
    [ # Nested expression.
        "OR",
        ["offer_id", "id1"],
        ["offer_id", "id2"],
        # More operands here...
    ],
    # More operands here...
])

# Optional sorting.
# String or list of strings.

params['sort'] = [
    'offer_id_asc',  # sort by id ascending
    'datetime_desc', # then by datetime descending
]

# Optional page number.
# Default 1.

params['page'] = 1

# Optional page size.
# Maximum 1000000.
# Default 100.

params['page_size'] = 100

# Optional timezone.
# Default `UTC`.
# Your value is here https://report.fraudscore.ai/account_settings
# Example: `Timezone settings` `Europe/Moscow (UTC+3)`
# Usage: `params['tz'] = 'Europe/Moscow'`

params['tz'] = 'UTC'

r = requests.get(url, params, stream=True)

print('Request URL', r.url)
# `https://get.fraudscore.ai/channel_id/install?key=user_key&field=datetime&field=offer_id&field=affiliate_id&field=ipv4_str&field=ua&filter=%5B%22AND%22%2C+%5B%22date_ge%22%2C+%222024-01-01%22%5D%2C+%5B%22date_le%22%2C+%222024-06-01%22%5D%2C+%5B%22OR%22%2C+%5B%22offer_id%22%2C+%22id1%22%5D%2C+%5B%22offer_id%22%2C+%22id2%22%5D%5D%5D&sort=offer_id_asc&sort=datetime_desc&page=1&page_size=100&tz=UTC`

# Response format is JSON lines. Read it line by line.
# That's why we passed `stream=True` above.

for line in r.iter_lines():
    # Each line is JSON.
    # Decode it and have fun!

    data = json.loads(line)

Download the file events_grouping.py or review the code below:

events_grouping.py

#!/usr/bin/env python3
# coding: utf8

# Events Grouping Request Example

import json
import requests

# Your channel id.

CHANNEL = 'channel_id'

# Your user key.

USER_KEY = 'user_key'

# Event type.
# Possible values:
# install, click, impression, custom.

EVENT = 'install'

# This is how URL looks like.

url = f'https://get.fraudscore.ai/{CHANNEL}/{EVENT}/groups'

# Initialize request parameters.
# User key required.

params = dict(key = USER_KEY)

# List of fields to group.
# String or list of strings.

params['group'] = [
    'date',
    'ipv4_str',
]

# List of special group fields we need.
# String or list of strings.

params['field'] = [
    'any_offer_name',
    'any_affiliate_name',
]

# Optional filter expression.
# String (JSON).
# Expression format: ["operator", operand, operand, ...]
# Operand format: ["field", "value"]
# Nested expressions are supported. Example:
# `date >= "2024-01-01" AND date <= "2024-06-01" AND (offer_id = "id1" OR offer_id = "id2")`

params['filter'] = json.dumps([
    "AND",
    ["date_ge", "2024-01-01"],
    ["date_le", "2024-06-01"],
    [ # Nested expression.
        "OR",
        ["offer_id", "id1"],
        ["offer_id", "id2"],
        # More operands here...
    ],
    # More operands here...
])

# Optional filter after grouping.
# Works the same way as `filter` param.
# Example: return groups where count >= 10

params['having'] = json.dumps(
    ["count_ge", "10"]
)

# Optional sorting.
# String or list of strings.

params['sort'] = [
    'any_offer_name_asc', # sort by offer_name ascending
    'any_affiliate_name_desc', # then by affiliate_name descending
]

# Optional page number.
# Default 1.

params['page'] = 1

# Optional page size.
# Maximum 1000000.
# Default 100.

params['page_size'] = 100

# Optional timezone.
# Default `UTC`.
# Your value is here https://report.fraudscore.ai/account_settings
# Example: `Timezone settings` `Europe/Moscow (UTC+3)`
# Usage: `params['tz'] = 'Europe/Moscow'`

params['tz'] = 'UTC'

# Perform GET request.
# Stream mode recommended.

r = requests.get(url, params, stream=True)

print('Request URL', r.url)
# `https://get.fraudscore.ai/channel_id/install/groups?key=user_key&group=date&group=ipv4_str&field=any_offer_name&field=any_affiliate_name&filter=%5B%22AND%22%2C+%5B%22date_ge%22%2C+%222024-01-01%22%5D%2C+%5B%22date_le%22%2C+%222024-06-01%22%5D%2C+%5B%22OR%22%2C+%5B%22offer_id%22%2C+%22id1%22%5D%2C+%5B%22offer_id%22%2C+%22id2%22%5D%5D%5D&having=%5B%22count_ge%22%2C+%2210%22%5D&sort=any_offer_name_asc&sort=any_affiliate_name_desc&page=1&page_size=100&tz=UTC`

# Response format is JSON lines. Read it line by line.
# That's why we passed `stream=True` above.

for line in r.iter_lines():
    # Each line is JSON.
    # Decode it and have fun!

    data = json.loads(line)