ThreatMetrix

ThreatMetrix (now part of LexisNexis Risk Solutions) is a behavioral analytics and device fingerprinting platform used extensively in financial services, retail, and insurance. It collects device and behavioral signals to produce a session token that is submitted with account creation, login, and payment requests. Without a valid ThreatMetrix session, transactions are flagged as high-risk or blocked.

Supported Types

Type	Description
ThreatMetrixToken	Generates a ThreatMetrix session intelligence token.

Parameters

Parameter	Type	Required	Description
type	string	Yes	ThreatMetrixToken
websiteURL	string	Yes	The URL of the ThreatMetrix-protected page
proxy	string	No	Proxy in http://user:pass@host:port format. Should match the IP used in the transaction.

Create Task Request

{
  "clientKey": "YOUR_API_KEY",
  "task": {
    "type": "ThreatMetrixToken",
    "websiteURL": "https://example.com/login",
    "proxy": "http://user:pass@1.2.3.4:8080"
  }
}

Response

{
  "errorId": 0,
  "taskId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing"
}

Solution Object

{
  "token": "tmx_session_abc123xyz..."
}

Field	Type	Description
token	string	The ThreatMetrix session token. Include this in the protected request as required by the target site’s ThreatMetrix integration (typically as a hidden form field or request parameter).

How to Use

1. Identify the ThreatMetrix session token field in the target site’s request (commonly tmx_session_id, iovation_blackbox, or a site-specific parameter name).
2. Submit a ThreatMetrixToken task for the protected page URL.
3. Poll until the task is ready.
4. Include the returned token in the appropriate field of your protected request.

Caution

ThreatMetrix session tokens incorporate device and network signals. Use the same proxy IP for both the token generation task and the subsequent protected request. The session token is short-lived and must be used quickly.

Note

ThreatMetrix is commonly integrated into login, account registration, and checkout flows at banks, insurance providers, and major retailers. The exact field name for the token varies by integration.

Code Examples

Python

import requests
import time

API_KEY = "YOUR_API_KEY"

response = requests.post("https://api.ucaptcha.net/createTask", json={
    "clientKey": API_KEY,
    "task": {
        "type": "ThreatMetrixToken",
        "websiteURL": "https://example.com/login",
        "proxy": "http://user:pass@1.2.3.4:8080"
    }
})
task_id = response.json()["taskId"]

while True:
    result = requests.post("https://api.ucaptcha.net/getTaskResult", json={
        "clientKey": API_KEY,
        "taskId": task_id
    }).json()
    if result["status"] == "ready":
        token = result["solution"]["token"]
        print("Token:", token)
        break
    elif result["status"] == "failed":
        print("Error:", result.get("errorDescription"))
        break
    time.sleep(5)

JavaScript

const API_KEY = "YOUR_API_KEY";

const { taskId } = await fetch("https://api.ucaptcha.net/createTask", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    clientKey: API_KEY,
    task: {
      type: "ThreatMetrixToken",
      websiteURL: "https://example.com/login",
      proxy: "http://user:pass@1.2.3.4:8080"
    }
  })
}).then(r => r.json());

while (true) {
  const result = await fetch("https://api.ucaptcha.net/getTaskResult", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ clientKey: API_KEY, taskId })
  }).then(r => r.json());

  if (result.status === "ready") {
    console.log("Token:", result.solution.token);
    break;
  } else if (result.status === "failed") {
    console.error("Error:", result.errorDescription);
    break;
  }
  await new Promise(r => setTimeout(r, 5000));
}

cURL

curl -X POST https://api.ucaptcha.net/createTask \
  -H "Content-Type: application/json" \
  -d '{
    "clientKey": "YOUR_API_KEY",
    "task": {
      "type": "ThreatMetrixToken",
      "websiteURL": "https://example.com/login"
    }
  }'

Provider Coverage

• RiskByPass

RiskByPass API

If you are using the RiskByPass compatibility layer, the equivalent task_type is threatmetrix.