POST /v1/verify/upi/batch — Batch UPI Verification

The Batch Verify endpoint lets you submit up to 100 UPI Virtual Payment Addresses in a single API call and receive a risk verdict for each one. You get the same FLAGGED / CLEARED verdicts, confidence scores, and cluster details as the single-VPA endpoint, plus top-level summary counts — flagged_count and cleared_count — so you can triage results without counting rows yourself. This endpoint is designed for bulk onboarding checks, overnight screening runs, and any workflow where you need to evaluate a list of VPAs at once.

Endpoint

POST https://api.fraudtraceai.com/v1/verify/upi/batch

Request Headers

Authorization

string

required

Your API key, passed as a Bearer token: Authorization: Bearer YOUR_API_KEY

Content-Type

string

required

Must be application/json.

Request Body

upis

string[]

required

An array of UPI Virtual Payment Addresses to verify. Each item must be a valid VPA in the format handle@provider (e.g., user@ybl). You can send between 1 and 100 VPAs per request.

{
  "upis": ["user1@ybl", "user2@okaxis", "merchant3@paytm"]
}

The maximum batch size is 100 VPAs per request. If you need to screen more than 100 VPAs, split your list into chunks of 100 and send them as sequential requests. See the batch lookup guide for a pagination pattern.

Request Examples

curl -X POST https://api.fraudtraceai.com/v1/verify/upi/batch \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"upis": ["user1@ybl", "user2@okaxis", "merchant3@paytm"]}'

import requests

payload = {
    "upis": ["user1@ybl", "user2@okaxis", "merchant3@paytm"]
}

response = requests.post(
    "https://api.fraudtraceai.com/v1/verify/upi/batch",
    headers={
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json=payload,
)

data = response.json()
print(f"Flagged: {data['flagged_count']} / Total: {data['total']}")

for result in data["results"]:
    print(result["upi"], result["status"], result.get("confidence"))

Response

The response body contains a results array — one entry per submitted VPA in the same order as your input — along with top-level summary counts.

{
  "results": [
    {
      "upi": "user1@ybl",
      "status": "FLAGGED",
      "confidence": 0.91,
      "risk_category": "mule",
      "cluster_id": "MC-2104",
      "cluster_size": 7,
      "evidence_count": 2
    },
    {
      "upi": "user2@okaxis",
      "status": "CLEARED",
      "confidence": null,
      "risk_category": null,
      "cluster_id": null,
      "cluster_size": 0,
      "evidence_count": 0
    },
    {
      "upi": "merchant3@paytm",
      "status": "FLAGGED",
      "confidence": 0.67,
      "risk_category": "gambling",
      "cluster_id": null,
      "cluster_size": 0,
      "evidence_count": 1
    }
  ],
  "total": 3,
  "flagged_count": 2,
  "cleared_count": 1
}

Top-Level Response Fields

results

array

An ordered array of result objects, one per VPA submitted. The order matches your input array.

Show result object fields

results[].upi

string

The UPI VPA that was evaluated. Echoed back for easy correlation.

results[].status

string

The risk verdict. Either FLAGGED or CLEARED.

results[].confidence

float | null

Confidence score between 0.0 and 1.0. Returns null when status is CLEARED.

results[].risk_category

string | null

The primary risk category: mule, gambling, phishing, scam, or nbfc_impersonation. Returns null when status is CLEARED.

results[].cluster_id

string | null

The cluster identifier if this VPA belongs to a known mule cluster (e.g., MC-2104). Returns null if not clustered or CLEARED.

results[].cluster_size

integer

Number of VPAs in the cluster. Returns 0 when cluster_id is null.

results[].evidence_count

integer

Total evidence items associated with this VPA. Returns 0 when status is CLEARED.

total

integer

The total number of VPAs evaluated in this batch. Matches the length of your input upis array.

flagged_count

integer

The number of VPAs in this batch that returned status: FLAGGED.

cleared_count

integer

The number of VPAs in this batch that returned status: CLEARED.

Batch results include key risk signals but omit the full sources array to keep response payloads compact. If you need the complete list of evidence sources for a specific VPA — for example, to satisfy a compliance audit trail — call GET /v1/verify/upi for that VPA individually.

Error Codes

HTTP Status	Meaning
`400 Bad Request`	The request body is missing, malformed, contains an invalid VPA format, or the `upis` array exceeds 100 items.
`401 Unauthorized`	The `Authorization` header is missing or the API key is invalid.
`429 Too Many Requests`	You have exceeded your rate limit. Check the `Retry-After` header and retry after the indicated delay.
`500 Internal Server Error`	An unexpected error occurred on the FraudTrace side. Retry with exponential back-off.

Submitting more than 100 VPAs in a single request returns a 400 error. Chunk large lists into batches of 100 and iterate sequentially or with controlled concurrency to stay within rate limits.

Overview

MuleTrace

CyberTrace

Mobile Trace

POST /v1/verify/upi/batch — Batch UPI Verification

Endpoint

Request Headers

Request Body

Request Examples

Response

Top-Level Response Fields

Error Codes

​Endpoint

​Request Headers

​Request Body

​Request Examples

​Response

​Top-Level Response Fields

​Error Codes

Endpoint

Request Headers

Request Body

Request Examples

Response

Top-Level Response Fields

Error Codes