verisoul-lookup

# 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: ```bash 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: ```bash bq query --use_legacy_sql=false "SELECT user_id FROM \`YOUR_GCP_PROJECT.prod.core_user_facts\` WHERE user_email = 'user@example.com' 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: ```json { "project_id": "YOUR_VERISOUL_PROJECT_ID", "request_id": "EXAMPLE_REQUEST_ID", "account": { "id": "user_id", "email": "user@example.com", "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": "user@example.com", "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: ```json { "message": "Account not found", "error": "Bad Request", "statusCode": 400 } ```