verisoul-lookup

name

verisoul-lookup

description

Look up a user account in Verisoul to check for fraud signals and account authenticity. Use when given an email address (e.g. from a fraud investigation) and you need to verify the account's legitimacy, check risk scores, and analyze email domain and device signals. Returns detailed account information including decision (Real/Fake), risk scores, email analysis, and device/network risk signals. Part of the fraud-bot skill suite.

Verisoul Lookup

Check an account in Verisoul and retrieve fraud risk assessment data.

Schema config

The bq lookup below uses the default logical mapping: project YOUR_GCP_PROJECT and table core_user_facts (dataset prod). Replace them with your physical names from config/schema.json (see SCHEMA.md).

Auth

Requires VERISOUL_API_KEY env var. Uses the Verisoul production API endpoint.

Usage

By User ID (Recommended)

If you have a Warp user ID, use it directly:

curl -s -X GET "https://api.prod.verisoul.ai/account/EXAMPLE_USER_ID" \
  -H "x-api-key: $VERISOUL_API_KEY" \
  -H "Content-Type: application/json"

By Email

If you only have an email, first look up the user ID from BigQuery:

bq query --use_legacy_sql=false "SELECT user_id FROM \`YOUR_GCP_PROJECT.prod.core_user_facts\` WHERE user_email = '[e-mail]' LIMIT 1"

Then use the returned user_id in the curl command above, replacing EXAMPLE_USER_ID with your actual user ID.

Response Format

Returns a JSON object with the following structure:

{
  "project_id": "YOUR_VERISOUL_PROJECT_ID",
  "request_id": "EXAMPLE_REQUEST_ID",
  "account": {
    "id": "user_id",
    "email": "[e-mail]",
    "metadata": {},
    "group": ""
  },
  "decision": "Real" | "Fake",
  "account_score": 0.0,
  "bot": 0.0,
  "multiple_accounts": 0.0,
  "risk_signals": 0.0,
  "accounts_linked": 0,
  "country": "US",
  "countries": ["US"],
  "email": {
    "email": "[e-mail]",
    "disposable": false,
    "personal": true,
    "valid": true,
    "domain_type": "personal" | "business" | "education" | "impersonation" | "disposable" | "relay" | "invalid",
    "email_score": 0.0,
    "trust_signals": ["email_age_greater_than_5_years"],
    "risk_signals": ["domain_impersonation_type"],
    "num_account_from_domain": 1
  },
  "risk_signal_average": {
    "device_risk": 0.0,
    "proxy": 0.0,
    "vpn": 0.0,
    "tor": 0.0,
    "spoofed_ip": 0.0,
    "datacenter": 0.0,
    "recent_fraud_ip": 0.0,
    "impossible_travel": 0.0,
    "device_network_mismatch": 0.0,
    "location_spoofing": 0.0
  },
  "unique_devices": {
    "1_day": 1,
    "7_day": 1
  },
  "unique_networks": {
    "1_day": 1,
    "7_day": 1
  }
}

Key Fields for Fraud Investigation

• decision: "Real" or "Fake" — overall account authenticity determination
• account_score: 0.0–1.0, where 1.0 is highest risk
• email.domain_type: "impersonation" domains are high-risk; "personal" and "business" are generally trustworthy
• email.email_score: 0.0–1.0, where 1.0 is highest risk for the email itself
• risk_signal_average: Device/network risk breakdown (VPN, Tor, datacenter, proxy, spoofed IP, etc.)
• accounts_linked: Number of other accounts linked to this one (indicator of coordinated abuse)

Error Handling

If the account is not found, Verisoul returns:

{
  "message": "Account not found",
  "error": "Bad Request",
  "statusCode": 400
}