Docs · Concepts

Concepts

Four ideas to internalize before you wire Tellr in: the 18-digit ID, composite IDs, verdicts, and thresholds. They are the entire mental model.

tellr_id

Every tracked end user gets one stable 18-digit decimal identifier. The same person across multiple check calls reuses the same tellr_id — even when they swap email, IP, browser, and card.

Store it alongside your internal user record. From then on, the dashboard, the API, and your support tools can all pivot on it.

sql

ALTER TABLE users ADD COLUMN tellr_id CHAR(18);
CREATE INDEX ON users (tellr_id);

Composite IDs

Tellr derives four SHA-256 hashes per check, in increasing order of identity strength:

Hash	Inputs	Match weight
`hardware_id`	canvas, WebGL, audio, CPU, RAM, screen, platform	+45
`browser_id`	UA, fonts, voices, locale, permissions	+30
`network_id`	ASN, subnet, JA4, HTTP/2 fingerprint	+25
`identity_id`	canonical email, E.164 phone, card fingerprint	+50

A new check is a repeat if any composite ID matches an existing end_user in your project. Multiple matches are stronger than one.

Verdicts and scores

Each check returns a 0–100 score and one of three verdicts. The score is the sum of every signal contribution, capped at 100. Thresholds are configurable per project.

Verdict	Default range	Suggested action
`allow`	0–49	Let through silently.
`flag`	50–79	Send to manual review or extra friction (CAPTCHA, email confirmation).
`block`	80–100	Refuse the signup at the API.

Custom thresholds

Both thresholds are per project, editable in Settings or via the API on every check. Lower thresholds catch more abuse but raise false positives.

json

{
  "session_token": "tk_sess_xxx",
  "end_user": { "email": "alice@example.com" },
  "options": { "block_threshold": 70, "flag_threshold": 40 }
}

Explanation array

Every check response includes an explanation array of signal contributions, sorted by weight descending. It is designed to be displayed verbatim to your support staff.

json

"explanation": [
  { "signal": "hardware_id_match", "weight": 45, "description": "Same device hardware as user 194827361092847362" },
  { "signal": "ip_vpn",            "weight": 25, "description": "VPN: NordVPN" },
  { "signal": "email_disposable",  "weight": 30, "description": "Disposable email: mailinator.com" }
]