TrialShield API v1

Introduction

TrialShield combines 100+ identity, network, payment, behavior, and content signals into a single 0–100 risk score. The most common integration is two API calls: /v1/verify at signup, and /v1/track for continuous monitoring while the user is on a trial.

All endpoints are hosted at https://trialshield.cc/api/v1.

Quickstart

1. Create an account and request a free trial.
2. Once approved, copy your API key from Dashboard → Settings.
3. Send your first verification:

Authentication

Every customer-facing endpoint accepts the API key in either header. Pick one — both are equivalent.

Plans & limits

Each plan unlocks a feature set and a per-key rate limit. The check happens once per request, before your handler runs.

Verify

Score a signup or login event. Returns a 0–100 risk score, a recommended decision, and the signals that fired. At least one of email, phone or ip is required.

Request body

Response

Example

const res = await fetch("https://trialshield.cc/api/v1/verify", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.TS_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    email:    "user@example.com",
    ip:       req.ip,
    metadata: { signup_source: "organic" },
  }),
});
const result = await res.json();
if (result.decision === "DENY") throw new Error("trial_abuse");

Track

Continuous monitoring after signup. Pass any user activity (file upload, AI query, GitHub link, login) and TrialShield resolves identity, fingerprints content, and surfaces duplicate accounts that share the same device, IP, or content.

Request body

Response

Monitor

Lightweight event log. Useful when you want to feed second-order signals (data exports, suspicious actions) without running the full Track pipeline.

Request body

Feedback

Tell us when our decision was wrong (false positive / false negative). The signal flows back into the model.

Create KYC session

Generate a hosted verification link for a specific end-user. The link expires after 30 minutes. Document images are purged after 30 days; cryptographic hashes are kept indefinitely for cross-tenant reuse detection.

Request body

Response

Get KYC session

Poll for the result of a KYC session. Returns status, level, the full result (decision, score, signals) once status is completed, plus timestamps.

Delete a user (GDPR / CCPA)

Erase every record we hold for an end-user — risk events, device graph entries, monitoring events, identity anchors, and the user row itself. Resolves id as a TrialShield user UUID by default; pass ?type=email or ?type=phone to look up by hash.

Tenant-scoped: the user must have at least one risk event tied to one of your API keys. Cross-tenant deletes are rejected with 403.

Export a user (GDPR)

Returns the user record plus all stored events, anchors and risk evaluations as JSON. Same tenant scoping as DELETE.

Decisions

Default thresholds. Override per API key from Settings → Module weights.

Risk signals

Every signals[] entry has a module, signal name, severity, and a human description.

Errors

Errors come back with an error string and a stable machine-readable code.

Rate limits

Every key has a per-minute window. The current limit comes from your plan unless you have an override from sales. Exceeded requests return 429 with the code RATE_LIMIT_EXCEEDED. The response includes X-RateLimit-Limit so you can back off.

Health

Unauthenticated. Returns {"status":"ok"} when the API is reachable. Use it as your uptime-monitor target.