API Documentation

Complete reference for the TrialShield API v1.

🔑 Authentication

All API requests require an API key passed via the X-API-Key header or Authorization: Bearer <key> header.

headers
X-API-Key: ts_your_api_key_here

// or

Authorization: Bearer ts_your_api_key_here

POST/api/v1/verify

Main verification endpoint. Evaluates user risk across all 12 modules and returns an ALLOW/DENY/CHALLENGE decision with a risk score (0-100).

Request Body

Field	Type	Required	Description
`email`	string	*	User email address
`phone`	string	*	Phone number (E.164 format preferred)
`ip`	string	*	User IP address (auto-detected if not provided)
`deviceFingerprint`	object	No	Device fingerprint from client SDK
`sessionId`	string	No	Session identifier for behavioral tracking
`metadata`	object	No	Additional context (mouseEntropy, keystrokePattern, timeOnPage)

* At least one of email, phone, or ip is required.

Response

200 OK
{
  "id": "uuid",
  "decision": "ALLOW" | "DENY" | "CHALLENGE",
  "riskScore": 0-100,
  "signals": [
    {
      "module": "EMAIL" | "PHONE" | "IP" | "DEVICE" | "BEHAVIOR" | "GRAPH" | "RULES",
      "signal": "DISPOSABLE_EMAIL",
      "severity": "LOW" | "MEDIUM" | "HIGH" | "CRITICAL",
      "description": "Human-readable explanation",
      "value": "optional additional data"
    }
  ],
  "breakdown": {
    "emailScore": 0,
    "phoneScore": 0,
    "ipScore": 0,
    "deviceScore": 0,
    "behaviorScore": 0,
    "graphScore": 0,
    "finalScore": 0,
    "weights": { ... }
  },
  "challenge": {
    "type": "NONE" | "INVISIBLE_CAPTCHA" | "PHONE_VERIFICATION" | "MANUAL_REVIEW",
    "tier": "LOW" | "MEDIUM" | "HIGH" | "CRITICAL",
    "actions": ["require_phone_verification", ...]
  },
  "enrichment": { ... },
  "processingTimeMs": 42,
  "timestamp": "2026-03-11T00:00:00.000Z"
}

Other Endpoints

GET/api/v1/healthSystem health check — module status, external API connectivity

POST/api/v1/monitorPost-signup event tracking — usage velocity and anomaly detection

POST/api/v1/feedbackReport abuse/legitimate confirmation for model improvement

GET/api/v1/keysList all API keys

POST/api/v1/keysCreate new API key

GET/api/v1/auditQuery audit logs (GDPR compliant)

GET/api/v1/statsDashboard statistics and analytics

GET/api/v1/users/:idExport user data (GDPR)

DELETE/api/v1/users/:idDelete user data (GDPR right to erasure)

📦 Client SDK

Add the TrialShield SDK to your signup page for device fingerprinting and behavioral biometrics.

integration.html
<!-- Add SDK to your page -->
<script src="https://your-api.com/sdk/trialshield.js"></script>

<script>
  // Initialize
  const ts = new TrialShield({
    apiKey: 'ts_your_key',
    apiUrl: 'https://your-api.com'
  });

  // On signup form submit
  document.getElementById('signup-form')
    .addEventListener('submit', async (e) => {
      e.preventDefault();

      const result = await ts.verify({
        email: document.getElementById('email').value,
        phone: document.getElementById('phone').value
      });

      if (result.decision === 'ALLOW') {
        // Proceed with signup
        submitSignup();
      } else if (result.decision === 'CHALLENGE') {
        // Show verification step
        showChallenge(result.challenge);
      } else {
        // Block signup
        showError('Unable to create account.');
      }
    });
</script>

🚨 Signal Reference

Signal	Module	Severity	Description
`DISPOSABLE_EMAIL`	EMAIL	CRITICAL	Temporary/disposable email domain detected
`NO_MX_RECORDS`	EMAIL	HIGH	Domain has no mail server records
`BREACHED_EMAIL`	EMAIL	HIGH	Email found in data breaches (HIBP)
`VOIP_NUMBER`	PHONE	HIGH	Virtual/VOIP phone number detected
`VPN_DETECTED`	IP	HIGH	VPN or proxy server detected
`TOR_EXIT_NODE`	IP	CRITICAL	TOR exit node IP address
`HEADLESS_BROWSER`	DEVICE	CRITICAL	Automated/headless browser detected
`MULTI_ACCOUNT_DEVICE`	DEVICE	HIGH	Same device used for multiple accounts
`HIGH_SIGNUP_VELOCITY_IP`	BEHAVIOR	HIGH	Too many signups from same IP
`COORDINATED_ATTACK`	GRAPH	CRITICAL	Multiple signals suggest organized abuse