FraudSense Developer Docs

Real-time device intelligence and fraud scoring for banks and fintechs. 44 signals, 4 combined patterns, plain English reasons. Integrate in 10 minutes.

What is FraudSense?

FraudSense is a device intelligence SDK and API that detects fraud at the device level — before transactions are processed. It runs silently inside your React Native app, evaluates 44 signals across 8 categories, and returns a calibrated risk score with confidence labels and plain English reasons.

Signal categories

How it works

// 1. SDK initializes silently at app startup
// 2. 7 collectors run in background (device, sensor, location, battery, network, behavior, security)
// 3. At a transaction point, your app calls getReport()
// 4. RiskEngine evaluates 44 signals → computes score 0–100
// 5. stableScore averages last 3 reports to eliminate first-load spikes
// 6. Full report returned with confidence labels + plain English reasons

Your App → FraudSense SDK → RiskEngine → Score + Labels + Summary + Patterns

Base URL

https://api.getfraudsense.com

Quick Start

Get from zero to a working risk score in under 10 minutes.

npm install fraudsense-sdk

npx expo install expo-battery expo-brightness expo-crypto expo-device \
  expo-location expo-network expo-screen-orientation \
  expo-secure-store expo-sensors

import FraudSense from 'fraudsense-sdk';

await FraudSense.init({
  apiKey:        'fs_live_xxxx',
  endpoint:      'https://api.getfraudsense.com',
  collectGPS:    true,
  trustedRegion: 'AE',  // reduces expat false positives
  debug:         false,
});

// At login, payment, or withdrawal
const report = await FraudSense.getReport();

// Use stableScore after 3+ reports (recommended)
const level = report.risk.isStable
  ? report.risk.stableLevel
  : report.risk.level;

if (level === 'CRITICAL') blockTransaction();
if (level === 'HIGH')     requireVerification();
if (level === 'MEDIUM')   requestOTP();
if (level === 'LOW')      allowTransaction();

// Plain English summary for your fraud team
console.log(report.risk.summary);

Authentication

FraudSense uses two authentication methods depending on the caller.

API Key — SDK and server-to-server calls

Pass your API key in the x-api-key header for all risk scoring and event endpoints.

x-api-key: fs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

JWT Token — dashboard and management

Use a Bearer token in the Authorization header for account management endpoints.

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Get a JWT token

curl -X POST https://api.getfraudsense.com/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@company.com","password":"yourpassword"}'

const res = await fetch('https://api.getfraudsense.com/v1/auth/login', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ email: 'you@company.com', password: 'yourpassword' }),
});
const { token } = await res.json();

SDK Installation

Requirements

Install via npm

npm install fraudsense-sdk

Install peer dependencies

npx expo install expo-battery expo-brightness expo-crypto expo-device \
  expo-location expo-network expo-screen-orientation \
  expo-secure-store expo-sensors

Add permissions (iOS) — app.json

{
  "expo": {
    "plugins": [
      ["expo-location", {
        "locationWhenInUsePermission": "Used to verify transaction safety."
      }]
    ]
  }
}

Initialization

Call FraudSense.init() once at app startup — ideally on the splash screen before navigating to login.

import FraudSense from 'fraudsense-sdk';

await FraudSense.init({
  apiKey:        'fs_live_xxxx',                      // Required
  endpoint:      'https://api.getfraudsense.com',       // Required
  collectGPS:    true,                                 // Optional — default false
  trustedRegion: 'AE',                                 // Optional — ISO country code
  autoFlush:     true,                                 // Optional — default true
  flushInterval: 30000,                               // Optional — ms, default 30s
  debug:         false,                               // Optional — console logs
});

Configuration options

Behavior Hooks

Wire up these hooks in your components to collect behavioral signals. The more hooks you add, the more accurate the interactionScore becomes.

Tap recording

import BehaviorCollector from 'fraudsense-sdk/collectors/BehaviorCollector';

<TouchableOpacity
  onPress={(e) => {
    BehaviorCollector.recordTap(e.nativeEvent.locationX, e.nativeEvent.locationY);
    handleAction();
  }}
/>

Text change / paste detection

Paste detection works automatically via text length jump analysis — no onPaste prop needed.

<TextInput
  onChangeText={(text) => {
    BehaviorCollector.recordTextChange('email', text); // auto-detects paste
    setEmail(text);
  }}
/>

<TextInput
  onChangeText={(text) => {
    BehaviorCollector.recordTextChange('password', text);
    setPassword(text);
  }}
/>

Scroll recording

<ScrollView
  onScroll={(e) => BehaviorCollector.recordScroll(e.nativeEvent.contentOffset.y)}
  scrollEventThrottle={16}
>

Screen transition recording

useEffect(() => {
  BehaviorCollector.recordScreenTransition('PaymentScreen');
}, []);

SDK Methods

getReport()

Returns a full risk report for the current session. Use risk.stableScore and risk.stableLevel after 3+ reports for more accurate scoring.

const report = await FraudSense.getReport();

console.log(report.risk.stableScore);   // 0–100, averaged over last 3
console.log(report.risk.stableLevel);   // LOW / MEDIUM / HIGH / CRITICAL
console.log(report.risk.isStable);      // true after 3+ reports
console.log(report.risk.summary);       // plain English verdict
console.log(report.risk.triggered);     // array of fired signals with reasons
console.log(report.risk.patternsDetected); // number of combined patterns fired

getRiskScore()

Returns just the score and level. Lighter than getReport() if you only need the number.

const { score, level, triggered } = await FraudSense.getRiskScore();

getDeviceId()

Returns the stable SHA-256 device fingerprint. Persists via secure storage across sessions.

const deviceId = FraudSense.getDeviceId();
// Returns: "fs_a3f9b2c1d4e5..."

Other methods

Event Hooks

Subscribe to real-time events from the SDK using FraudSense.on(). Returns an unsubscribe function.

// Fires when SDK is initialized
FraudSense.on('ready', ({ deviceId, version }) => {
  console.log('SDK ready', deviceId);
});

// Fires after every getReport() call
FraudSense.on('report', (report) => {
  setRiskBadge(report.risk.stableLevel);
});

// Fires after every flush attempt
FraudSense.on('flush', ({ success, response }) => {
  if (!success) console.warn('Flush failed');
});

// Unsubscribe when component unmounts
const unsub = FraudSense.on('report', handler);
return () => unsub();

Auth Endpoints

Register

{
  "email":       "you@company.com",
  "password":    "SecurePass1!",
  "companyName": "Acme Bank"
}

{
  "token":  "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "apiKey": "fs_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "client": {
    "id":          "uuid...",
    "email":       "you@company.com",
    "companyName": "Acme Bank",
    "plan":        "free"
  }
}

Events Endpoint

The SDK automatically posts to this endpoint on every flush. You can also call it directly for server-side integrations.

Request body

{
  "deviceId":    "fs_a3f9b2c1...",
  "sessionId":   "1744123456789",
  "deviceProfile": {
    "model":      "iPhone 17 Pro Max",
    "os":         "iOS",
    "timezone":   "Asia/Dubai",
    "locale":     "en-US",
    "isEmulator": false,
    "isRooted":   false
  },
  "events": [{
    "type":             "RISK_REPORT",
    "riskScore":        17,
    "riskLevel":        "LOW",
    "triggeredSignals": [],
    "fingerprint":      "fs_xyz...",
    "sdkVersion":       "1.2.0",
    "timestamp":        1744123456789
  }]
}

Device History

curl https://api.getfraudsense.com/v1/risk/history/fs_abc123 \
  -H "x-api-key: fs_live_xxxx"

API Keys

Dashboard

Risk Signal Catalogue

FraudSense v1.2.0 evaluates 44 signals per session across 8 categories. Each signal includes a confidence rating and plain English reason returned in the report.

Device signals (9)

Security signals (3)

Network signals (5)

Behavior signals (12)

Sensor signals (5)

Location signals (3)

Battery signals (3)

Combined Pattern Detection

Beyond individual signals, FraudSense detects 4 combined attack patterns. Patterns fire when multiple correlated signals appear together — they carry extra weight because combinations are far more reliable than single signals.

Risk Labels

High-level labels explain why a device scored HIGH — more actionable than a raw score alone. Returned in risk.byCategory and the risk.summary field.

Response Format

Risk levels

Risk object schema (v1.2.0)

Triggered signal object

IP Intelligence

Collected automatically via ipapi.co on every session. No extra configuration needed.

Device History

Every device that calls the API gets a persistent history record. Accessible via /v1/risk/history/:deviceId.

Status Codes

Changelog

SDK v1.2.0 — April 2026

• Signal count expanded from 18 to 44 signals across 8 categories
• Added SecurityCollector — emulator detection with confidence score, root/jailbreak heuristics, proxy detection
• Added 4 combined pattern detectors — automation, location hiding, credential stuffing, device farm
• Added confidence labels (HIGH/MEDIUM/LOW) and plain English reasons per signal
• Added stableScore — averages last 3 reports to eliminate first-load spikes
• Added trustedRegion config — reduces expat false positives for UAE and MENA markets
• Added summary field — plain English verdict for fraud teams
• Added byCategory — signals grouped by category for easier client integration
• Added paste detection via text length jump analysis (no onPaste prop required)
• Added device integrity scoring — model vs OS cross-validation
• Added locale vs timezone mismatch signal
• Added region vs IP country mismatch signal
• Improved VPN detection — confidence score 0–1 instead of boolean, cross-checks carrier country vs IP country
• Improved NetworkCollector — live IP intelligence via ipapi.co (country, city, org, datacenter flag)
• Fixed battery level comparison (was checking 0–1 float, now correctly checks 0–100 integer)
• Fixed all collector export issues — added collect() method to SensorCollector, BatteryCollector, LocationCollector
• Fixed locale/timezone collection via getLocales()/getCalendars() for newer Expo versions

SDK v1.1.0 — April 2026

• Initial public release on npm as fraudsense-sdk
• 6 collectors: Device, Sensor, Location, Battery, Network, Behavior
• 18 signals in RiskEngine
• SHA-256 device fingerprinting via expo-secure-store
• Singleton pattern throughout SDK

API v1.0.0 — March 2026

• Initial launch at api.getfraudsense.com
• JWT authentication, email verification, API key management
• Free tier — 1,000 calls/month
• Admin panel with suspend/activate/email/usage controls
• AI chatbot (Claude Haiku) for developer support
• /demo interactive fraud scenarios
• Railway deployment with PostgreSQL and Prisma

Support

Contact

Email: support@getfraudsense.com

GitHub Issues: github.com/getfraudsense/fraudsense-api

Before reaching out

• Check the Status Codes section for common errors
• Verify your API key is active in the developer portal
• Make sure deviceId and sessionId are included in every request
• For SDK issues, enable debug: true and check console logs
• Use the AI chatbot on the portal for instant answers