# Verisoul Lookup

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

- Skill: `warpdotdev/verisoul-lookup` (Agent Skill)
- Install (CLI): `npx skillmds@latest add warpdotdev/verisoul-lookup`
- Raw SKILL.md: https://api.skillmd.com/api/skills/warpdotdev/verisoul-lookup/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: warpdotdev (https://skillmd.com/u/warpdotdev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/warpdotdev/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
}
```