Skip to main content

S2S API

This article provides a comprehensive guide to integrate ClearTrust S2S API.

S
Written by Sudarshan Nirwani
Updated over 7 months ago

Introduction

With the ever-growing challenge of fraud and invalid traffic in digital advertising, AdOps teams must deploy efficient tools to safeguard campaigns and revenue. The S2S API by ClearTrust addresses these challenges head-on, providing real-time monitoring and blocking of fraudulent and invalid traffic. This article serves as a guide for integrating S2S API into your systems, offering a seamless solution to manage traffic quality and protect your advertising efforts.

Key Features of S2S API

  1. Real-Time Traffic Monitoring
    S2S API evaluates traffic events (clicks, page views, app views) in real-time, returning a score 0 (clean), 1 (high risk), 2 (medium risk), 3 (low risk), -1 (Error). This allows businesses to make instantaneous decisions on blocking or allowing traffic.

  2. Configurable Filter Settings
    The platform allows for flexible filter configuration, enabling users to adjust fraud detection settings on a global, advertiser-specific, or publisher/affiliate-specific basis. This granularity ensures that users can tailor their traffic monitoring to meet specific needs.

  3. Dashboard & Reporting API
    The results of traffic analysis are available in a real-time dashboard, offering insights and detailed reports. For teams looking for deeper integration, a reporting API endpoint is available.

Integration Steps

Integrating S2S API into your systems is a straightforward process, allowing for real-time fraud detection and traffic scoring. Below are the steps to successfully set up S2SAPI:

  1. API Request Endpoints
    S2S API offers two API endpoints:

    • https://xxx.yyyy.zzz/ic3.php?m=AF&src=s2s&b=<parent_bizid>&s=<bizid>

    • https://xxx.yyy.zzz/ic3.php?m=AF&src=s2s&b=<parent_bizid>&s=<bizid>

    The requester can choose an endpoint based on performance needs.
    ​

  2. Traffic Quality Scoring
    S2S API scores each traffic event using predefined filters. Customers can configure these filters through ClearTrust's dashboard, enabling them to adjust traffic scanning and detection settings based on business requirements.
    ​

  3. Sample API Call
    A typical API request call looks like this:

    https://xxx.yyy.zzz/ic3.phpm=AF&src=s2s&b=9999&s=9999&ip=49.207.233.07

    This request returns a traffic quality score and a reason code, which can be used to decide whether to block or allow the traffic.

API Response Structure

S2S API responses are returned in JSON format, with the following traffic quality score and reason code:

  • Success: {"tqs":{"score":0,"reason":"CL"}}
    (Traffic is clean, safe to allow)

  • Error: {"tqs":{"score":-1,"reason":"ERR"}}
    (An error occurred during processing)

  • Fraud Detected: {"tqs":{"score":1,"reason":"BN"}}
    (High-risk traffic, should be blocked)

The traffic quality score ranges from -1 to 3, where:

  • 0 = Clean Traffic

  • 1 = High-Risk Traffic

  • 2 = Medium-Risk Traffic

  • 3 = Low-Risk Traffic

  • -1 = Error

Advanced Macros for Enhanced API Calls

To ensure accurate traffic analysis and reporting, S2S API supports the use of macros in API calls. These macros provide additional information that enhances ClearTrust's ability to filter traffic and generate detailed reports.
​

Suggested Macros

Here are the essential and optional macros to include in your API calls:

S.No

Parameters (case sensitive)

Mandatory(M) / Optional (O)

Description

Default

1

m

Mandatory

Mode

AF

2

src

Mandatory

Server to server

s2s

3

b

Mandatory

Business ID

Provided

4

s

Mandatory

Parent Business ID

Provided

5

ip

Mandatory

IP Address (v4/v6)

None

6

cid

Mandatory

Request ID

CIDMACRO

7

s1

Optional

Publisher ID / Source ID

S1MACRO

8

s2

Optional

Sub Publisher

S2MACRO

9

s3

Mandatory (for Web)

Referer Domain

S3MACRO

10

s4

Mandatory (for App)

App Bundle

S4MACRO

11

s5

Mandatory (for App)

App Version

S5MACRO

12

s6

Mandatory

User Agent

S6MACRO

13

s7

Optional

Geo City

S7MACRO

14

s8

Optional

XFF

S8MACRO

15

s9

Optional

Device ID

S9MACRO

16

s10

Optional

GAID

S10MACRO

17

s11

Optional

IDFA

S11MACRO

Example API Calls with Macros

  1. For Web (with GAID):
    ​https://xxx.yyy.zzz/ic3.php?m=AF&src=s2s&b=8888&s=9999&cid=19819383&ip=31.13.127.18&s1=10001&s2=20001&s3=www.geniee.jp&s4=S4MACRO&s5=S5MACRO&s6=Mozilla%2F5.0%20%28Windows%20NT%2010.0%3B%20Win64%3B%20x64%29%20AppleWebKit%2F537.36%20%28KHTML%2C%20like%20Gecko%29%20Chrome%2F42.0.2311.135%20Safari%2F537.36%20Edge%2F12.246&s7=tokyo&s8=31.13.127.18,70.41.3.18&s9=123456781234123412341234567890AB&s10=a3c5fde82f234907b9bed958f0d6bd69&s11=S11MACRO
    ​

  2. For App (with IDFA):
    ​

    https://xxx.yyy.zzz/ic3.php?m=AF&src=s2s&b=8888&s=9999&cid=19819383&ip=31.13.127.18&s1=10001&s2=20001&s3=S3MACRO&s4=com.myexample.app&s5=1.5.3&s6=Mozilla%2F5.0%20%28iPhone%3B%20CPU%20iPhone%20OS%2013_2_3%20like%20Mac%20OS%20X%29AppleWebKit%2F607&s7=tokyo&s8=31.13.127.18,70.41.3.18&s9=123456781234123412341234567890AB&s10=S10MACRO&s11=AEBE52E7-03EE-455A-B3C4-E57283966239
    ​
    These macro-supported API calls provide the flexibility needed to filter traffic based on device type, geography, and other factors.
    ​

    Conclusion


    The S2S API by ClearTrust is an essential tool for any AdOps team seeking to protect their digital advertising campaigns from fraud and invalid traffic. With real-time traffic scoring, configurable filters, and robust reporting capabilities, S2S API ensures that only legitimate traffic reaches your platform, optimising both performance and ROI.

    For further assistance with integrating S2S API or customising its settings, please reach out to our customer support team.


    ​

Related Articles
Threat Definitions & Corresponding Traps
Did this answer your question?