warpdotdev 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 = '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:
{
"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:
{
"message": "Account not found",
"error": "Bad Request",
"statusCode": 400
}