> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fraudtraceai.com/llms.txt
> Use this file to discover all available pages before exploring further.
# FraudTrace API Evidence Schema: Full Response Field Guide
> Complete field-by-field reference for the FraudTrace UPI verification API response, with FLAGGED and CLEARED JSON examples and decisioning guidance.
When you call `/v1/verify/upi`, FraudTrace returns a structured JSON object that tells you not just whether a VPA is flagged, but why — with confidence scores, cluster membership, sighting timestamps, and direct links to the sources where the VPA was found. This page documents every field in that response so you can build precise decisioning logic and communicate findings clearly to your risk, compliance, and customer-support teams.
## Top-level response fields
These fields appear at the root of every API response, for both `FLAGGED` and `CLEARED` results.
| Field | Type | Description |
| ---------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `upi` | string | The UPI VPA you queried, returned exactly as submitted (e.g., `deposit88@ybl`). |
| `status` | string | `FLAGGED` if the VPA is in the FraudTrace database with evidence; `CLEARED` if no evidence was found. |
| `confidence` | float \| null | Confidence score from `0.0` to `1.0` indicating certainty of mule classification. `null` for `CLEARED` responses. |
| `risk_category` | string \| null | Primary fraud classification: `mule`, `gambling`, `phishing`, `scam`, or `nbfc_impersonation`. `null` for `CLEARED`. |
| `cluster_id` | string \| null | The stable cluster identifier (e.g., `MC-2104`) if the VPA belongs to a mule cluster. `null` if unclustered or `CLEARED`. |
| `cluster_size` | integer \| null | Number of VPAs currently in the cluster. `null` if `cluster_id` is `null`. |
| `first_seen` | ISO 8601 \| null | Timestamp when this VPA was first indexed by FraudTrace. `null` for `CLEARED`. |
| `last_seen` | ISO 8601 \| null | Timestamp of the most recent sighting across any monitored source. `null` for `CLEARED`. |
| `sources` | array | Array of source objects (see below). Empty array `[]` for `CLEARED` responses. |
| `evidence_count` | integer | Total number of captured evidence items (screenshots, page captures) across all sources. `0` for `CLEARED`. |
### Risk category values
| Value | Fraud type |
| -------------------- | ------------------------------------------------------------------- |
| `mule` | Account used to receive and forward stolen funds |
| `gambling` | VPA found on illegal online gambling or betting deposit pages |
| `phishing` | VPA found on pages impersonating banks, NPCI, or government portals |
| `scam` | VPA found in investment scams, task-fraud, or advance-fee schemes |
| `nbfc_impersonation` | VPA found on pages impersonating registered NBFCs or lenders |
When a VPA appears in multiple fraud contexts, `risk_category` reflects the **primary** category with the strongest evidence signal.
## Source object fields
Each item in the `sources` array represents a single crawled source where the VPA was observed.
| Field | Type | Description |
| ---------------------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `url` | string | The URL of the source page where the VPA was found. |
| `category` | string | Category of the source: `gambling`, `phishing`, `scam`, or `telegram`. |
| `captured_at` | ISO 8601 | Timestamp when FraudTrace's crawler captured this evidence. |
| `screenshot_available` | boolean | `true` if an archived screenshot of the source page is available for review in the FraudTrace dashboard. |
Source URLs and screenshots are available for audit and case-building purposes. Access the FraudTrace dashboard to view archived screenshots for any `FLAGGED` response where `screenshot_available` is `true`.
## Example: FLAGGED response
The following is a representative response for a VPA that has been flagged with high confidence as part of a known mule cluster.
```json theme={null}
{
"upi": "deposit88@ybl",
"status": "FLAGGED",
"confidence": 0.94,
"risk_category": "gambling",
"cluster_id": "MC-2104",
"cluster_size": 47,
"first_seen": "2024-09-12T08:23:41Z",
"last_seen": "2025-01-03T14:55:10Z",
"sources": [
{
"url": "https://betquick247.com/deposit",
"category": "gambling",
"captured_at": "2024-09-12T08:23:41Z",
"screenshot_available": true
},
{
"url": "https://t.me/fastwin_deposits",
"category": "telegram",
"captured_at": "2024-11-19T17:04:22Z",
"screenshot_available": true
},
{
"url": "https://spinrush99.io/pay",
"category": "gambling",
"captured_at": "2025-01-03T14:55:10Z",
"screenshot_available": false
}
],
"evidence_count": 11
}
```
**Reading this response:**
* `confidence: 0.94` places this VPA in the **high confidence** band — a block or immediate escalation is recommended.
* `cluster_id: "MC-2104"` with `cluster_size: 47` means this VPA is linked to a network of 46 other flagged accounts.
* `first_seen` and `last_seen` are over three months apart, indicating sustained activity rather than a one-off appearance.
* Two of three sources have `screenshot_available: true` — you can pull archived screenshots from the dashboard to support SAR filing or internal case documentation.
* `evidence_count: 11` means FraudTrace has captured 11 discrete evidence items across all sources, providing a strong evidentiary trail.
## Example: CLEARED response
```json theme={null}
{
"upi": "clean99@okaxis",
"status": "CLEARED",
"confidence": null,
"risk_category": null,
"cluster_id": null,
"cluster_size": null,
"first_seen": null,
"last_seen": null,
"sources": [],
"evidence_count": 0
}
```
A `CLEARED` status means the VPA has **not been observed** on any source currently monitored by FraudTrace. It does **not** constitute a guarantee that the VPA is legitimate or that the account holder is not involved in fraud. Apply your own additional risk controls — especially for high-value or first-time payees — regardless of a `CLEARED` response.
## Using the schema in your integration
When building your decisioning layer, consider the following patterns:
**Automated block on high confidence:**
```python theme={null}
response = fraudtrace.verify_upi(vpa="deposit88@ybl")
if response["status"] == "FLAGGED" and response["confidence"] >= 0.85:
block_transaction(reason="high_confidence_mule", cluster=response["cluster_id"])
```
**Cluster-aware escalation for medium confidence:**
```python theme={null}
if response["status"] == "FLAGGED" and 0.60 <= response["confidence"] < 0.85:
if response["cluster_id"] is not None:
escalate_to_review(vpa=response["upi"], cluster=response["cluster_id"])
else:
add_to_monitor_queue(vpa=response["upi"])
```
**Logging evidence for compliance:**
```python theme={null}
for source in response.get("sources", []):
log_evidence(
vpa=response["upi"],
source_url=source["url"],
category=source["category"],
captured=source["captured_at"],
has_screenshot=source["screenshot_available"]
)
```
Store the `cluster_id`, `confidence`, `first_seen`, and `last_seen` fields in your case management system alongside any transaction you block or escalate. These fields provide a ready-made audit trail for RBI inspection, internal compliance reviews, or law enforcement information requests.