Skip to content

FraudScan API

Clients can now subscribe to FraudScan's "test" webhook, that allows you receive to FraudScan data in real time. To get started you must first setup an API endpoint to accept the fields that we send in the webhook message, then ask us to begin sending data to that endpoint.

Subscribe to the Webhook

You'll need to provide your account manager with the webhook endpoint URL and a unique API Key, they will create an API account with those details. Once the account is setup you'll be subscribed, everytime FraudScan publishes a test our webhook will POST the relevant test data to your API.

Note

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

Example webhook POST request:

1
2
3
4
5
    curl -X POST \
    'https://client-api-entpoint.com/fraudscan-webhook' \
    -H 'x-api-key: client-api-key' \
    -H 'Content-Type: application/json' \
    -d '[JSON test-data]'

Note

There's a queueing system in place, so the webook messages may arrive with a minor delay. - Webook messaging follows FraudScan test-publishing policies, so if a "notice period" is set in a test, it will be applied here as well.

API Response

After your API receives the webhook request it needs to return the appropriate response. The webhook expects the response below, in order to remove the test from the queue and avoid sending duplicate tests.

1
{ "status": 200, "message": "success" }

In case of a request error, the response should follow the same format, i.e.

1
{ "status": 401, "message": "authorization failed" }

General Market tests

You can also subscribe to General Market tests. You can use the same endpoint and API key or different ones.

Assort your own tests from General Market ones by looking at the webhook message propery, gm. For your own tests the value will be false and for General Market tests it will be true.

Webhook Message

The payload of the webhook message is a JSON object that contains all the important "test" properties.

Key Description
date ISO datetime of test publication (UTC)
testId Test's ID String
gm General Market test Boolean
ref Test's reference number String
brand Service name String
companies List of companies involved Array
merchant Service merchant String
countryCode 2-digit country code String
country Full country name String
networkCode 2-digit network code String
network Full network name String
connection Network connection String
status Issue's compliance status String
trafficSource Test's traffic source String
serviceType Service category String
device Test's device String
testType Test's type String
paymentType Test's payment type String
appName Application name String
smsCode SMS shortcode String
smsKeyword SMS keyword String
textAd The advert link text String
publisherUrl Service URL String
landingUrl Test's landing page URL String
urlList List of all test's URLs and redirects Array
media List of test's assets showcasing the user's journey Array of objects (see details)
issue The issue object. Either Object or Null (see details)

Example payload:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
  {
    "date" : "2023-03-02T09:37:53.366Z",
    "testId" : "63fdfc22509fa0d07a0657ff",
    "gm" : false
    "ref" : "test 1234567",
    "brand" : "Top-top Games",
    "companies" : [
      "Company 1",
      "Company 2 (AG)",
      "Operator (MNO)",
      "Affiliate (AN)",
    ],
    "merchant" : "Company 1",
    "countryCode" : "UK",
    "country" : "United Kingdom",
    "networkCode" : "vf",
    "network" : "Vodafone",
    "connection" : "4G mobile",
    "status" : "high",
    "trafficSource" : "in-app",
    "serviceType" : "games",
    "device" : "smartphone",
    "testType" : "marketing test",
    "paymentType" : "carrier billing",
    "appName" : "Demo App",
    "smsCode" : "123456",
    "smsKeyword" : "STOP",
    "textAd" : "Demo text",
    "publisherUrl" : "http://publisher.example.com",
    "landingUrl" : "http://landing.test.com",
    "urlList" : "http://publisher.example.com\nhttps://otherpage.example.com\nhttp://landing.test.com",
    "media" : [
      {
        "asset" : "63f5e2bc7c0f756b9eef561f",
        "assetLink": "https://empello.net/asset/63f5e2bc7c0f756b9eef561f",
        "name" : "image_1.png",
        "ext" : "png"
      },
      ...
    ],
    "issue" : {
      "breach" : [
        {
          "type": "subscriptionauto",
          "label": "auto-subscription",
          "description": "The visitor is subscribed to a service without their consent. This includes iframe masking, app malware etc."
        }
      ],
      "breachNotes" : "Received the OTP and the welcome SMS for the subscription as soon as we installed the malware app. No concent was asked for nor given.",
      "assignee" : "Company 1",
      "regulator" : "Company 2 (AG)",
      "opened" : "2023-03-02T09:37:53.334Z"
    },
  }

Payload Details

Media Object

A single media object consists of:

Key Description
asset The ID of the file asset String
assetLink The fraudscan link of the asset String
name The file name of the asset String
ext The file extension, e.g. jpg String
url The URL where the asset was found/generated String
comment Comments associated with the asset String

Issue Object

The following issue properties are set:

Key Description
breach Description of the breaches that are found (Array of objects)
breachNotes Supplemental breach information
assignee The company responsible for fixing the issue (Null or String)
regulator The company responsible for verifying the issues (Null or String)
openedAt ISO datetime of when the issue was raised (UTC)

Note

A breach object consists of 3 key/value pairs. (type, label, description). If you need to group data by breach type, use the type one, as the breaches labels and descriptions are sometimes updated to better match the market requirements