Integration Guide

This guide covers end-to-end integration patterns for the most common Trustfull use cases: user onboarding, session monitoring, and login protection. Each section includes the API calls, data flow, and decisioning logic you need to implement.

Architecture Overview

A typical Trustfull integration follows this pattern:

1. Your application collects user data (phone, email, IP, device fingerprint)
2. Your backend sends this data to the Trustfull API
3. Trustfull returns enriched data, scores, and reason codes
4. Your application uses the response to make a decision (accept, review, or reject)

All API calls must originate from your backend. Never expose your API key in client-side code. The only exception is the JavaScript SDK used for device fingerprinting, which uses a separate public app key.

Use Case 1: User Onboarding

The Onboarding product is the most common starting point. It combines phone, email, and IP analysis into a single API call, and adds cross-signal consistency checks (e.g. whether the name from the email matches the name from the phone).

Step 1 — Collect User Data

During your registration form, collect:

• Phone number (including country code)
• Email address
• First and last name (optional, but enables name consistency checks)

The IP address is typically extracted from the incoming HTTP request on your server side.

Step 2 — Call the Onboarding API

curl -X POST https://api.trustfull.com/onboarding \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -d '{
    "phone": "3912345678",
    "email": "[email protected]",
    "ip": "82.56.23.100",
    "first_name": "Tony",
    "last_name": "Stark"
  }'

Step 3 — Apply Decisioning Logic

The response contains individual scores for each signal, cross-signal consistency checks, and reason codes. Here is a practical decisioning example:

import requests

def check_onboarding(phone, email, ip, first_name, last_name):
    response = requests.post(
        "https://api.trustfull.com/onboarding",
        headers={
            "Content-Type": "application/json",
            "x-api-key": "your-api-key-here"
        },
        json={
            "phone": phone,
            "email": email,
            "ip": ip,
            "first_name": first_name,
            "last_name": last_name
        }
    )
    data = response.json()

    # Check individual scores
    phone_cluster = data.get("phone_score_cluster")
    email_cluster = data.get("email_score_cluster")
    ip_cluster = data.get("ip_score_cluster")

    # Reject if any signal is very_low
    if "very_low" in [phone_cluster, email_cluster, ip_cluster]:
        return {"decision": "reject", "reason": "High-risk signal detected"}

    # Review if any signal is low or review
    if "low" in [phone_cluster, email_cluster, ip_cluster]:
        return {"decision": "review", "reason": "Suspicious signal detected"}

    if "review" in [phone_cluster, email_cluster, ip_cluster]:
        return {"decision": "review", "reason": "Mixed signals detected"}

    # Check for critical reason codes
    reason_codes = []
    for field in ["phone_reason_codes", "email_reason_codes", "ip_reason_codes"]:
        codes = data.get(field, "")
        if codes:
            reason_codes.extend(codes.split(","))

    critical_risk_codes = {"RP001", "RE002", "RE005", "RI003"}  # Disposable, Invalid, TOR
    if critical_risk_codes.intersection(reason_codes):
        return {"decision": "review", "reason": "Critical risk signal detected"}

    return {"decision": "accept"}

Step 4 — Act on the Decision

Store the resolution_id returned by Trustfull. It uniquely identifies this check and can be used for audit trails, dashboard lookups, and support investigations.

Use Case 2: Session Monitoring (Bot Detection)

The Session product detects bots, automated browsers, and device spoofing on your web pages. It requires integrating a lightweight JavaScript SDK on your frontend.

Step 1 — Add the JavaScript SDK

Add the Trustfull SDK to the pages you want to monitor. The SDK collects device fingerprint data, browser signals, and behavioral data (mouse movements, clicks, scroll events).

<script src="https://cdn.trustfull.com/sdk/v1/trustfull.js"></script>
<script>
  Trustfull.init({
    appKey: "TFB-your-app-key"
  });
</script>

The SDK generates a session_id that you will use to retrieve the session analysis.

For detailed SDK integration instructions, see Session Integration.

Step 2 — Retrieve Session Results

Once the SDK has collected enough data (typically after the user has interacted with the page), retrieve the session analysis from your backend:

curl -X GET "https://api.trustfull.com/session?session_id=YOUR_SESSION_ID" \
  -H "x-api-key: your-api-key-here"

Step 3 — Evaluate the Response

The Session response includes a score, cluster, and detailed signals about the session:

def evaluate_session(session_data):
    cluster = session_data.get("score_cluster")

    # Check for bot indicators
    is_bot = (
        session_data.get("has_automated_browser", False)
        or session_data.get("has_ai_agent", False)
        or session_data.get("navigator_web_driver", False)
    )

    is_spoofed = session_data.get("has_spoofed_device", False)

    if is_bot:
        return {"decision": "block", "reason": "Automated browser detected"}

    if is_spoofed:
        return {"decision": "block", "reason": "Device spoofing detected"}

    if cluster in ["very_low", "low"]:
        return {"decision": "challenge", "reason": "Suspicious session"}

    return {"decision": "allow"}

Key signals to monitor:

For the full list of session signals, see Session Data Catalogue.

Use Case 3: Login Protection

The Login product compares a returning user's device and network characteristics against their enrollment profile to detect account takeover (ATO). It works in two phases: enrollment (during onboarding or first login) and scoring (on subsequent logins).

Step 1 — Enrollment

During the user's first login or registration, enroll their device profile:

curl -X POST https://api.trustfull.com/login/enrollment \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -d '{
    "username": "tony.stark",
    "session_id": "session-abc-123"
  }'

The session_id must come from the JavaScript SDK running on the user's browser. This captures the device fingerprint, browser details, and IP address as the enrollment baseline.

Step 2 — Login Scoring

On subsequent logins, score the session against the enrollment profile:

curl -X POST https://api.trustfull.com/login/score \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-api-key-here" \
  -d '{
    "username": "tony.stark",
    "session_id": "session-xyz-789"
  }'

Step 3 — Evaluate the Login

The response includes a score, cluster, and specific match/mismatch signals:

def evaluate_login(login_data):
    cluster = login_data.get("score_cluster")

    if cluster in ["very_low", "low"]:
        return {
            "decision": "step_up",
            "reason": "Login does not match known device profile",
            "action": "Require OTP or security question"
        }

    if cluster == "review":
        return {
            "decision": "allow_with_monitoring",
            "reason": "Minor deviations from enrollment profile"
        }

    return {"decision": "allow"}

Key mismatch signals returned by the Login API:

For the complete list, see Login Data Catalogue and Reason Codes.

Error Handling

All Trustfull API responses include an HTTP status code. Handle errors gracefully in your integration:

Fail open or fail closed? Decide upfront what happens when the Trustfull API is unreachable. Most customers choose to fail open (allow the user through) for onboarding flows and fail closed (block the action) for high-risk transactions. Implement timeouts (we recommend 10-15 seconds) and fallback logic accordingly.

Latency Considerations

Trustfull offers two modes for most products:

To use low-latency mode, use the dedicated low-latency endpoints (e.g. /phone/low-latency). See the API Reference for details.

What's Next

• Your First API Call — Quick start with a single API request
• Understanding Scores — How to interpret scores and clusters
• Reason Codes — Full catalogue of risk and trust signals
• API Reference — Complete API specification