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"
   
   
     
     
     
     
      |  |  |  |  |  | 
     
     
     
     
  
   
     
     
     
     
     
     
     
     
     
     
  
   
     
     
  
   
     
     
  

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
}