Getting Started
Your First Request
Walk through a complete request/response cycle with the VerifyStack API.
Let's make your first fraud detection request using cURL. This works with both publishable and secret keys.
Making the Request
POST /api/v1/decidebash
curl -X POST https://verifystack.io/api/v1/decide \
-H "X-API-Key: sk_live_xxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{
"userId": "user_123",
"action": "login",
"email": "user@example.com",
"ip": "203.0.113.42",
"metadata": {
"flow": "password"
}
}'Understanding the Response
Response (200 OK)json
{
"success": true,
"data": {
"decision": "allow",
"score": 15,
"confidence": 0.97,
"confidencePercent": 97,
"reasons": ["LOW_RISK"],
"evidenceId": "evi_xxxx",
"requestId": "req_abc123def456",
"processingTimeMs": 23
},
"meta": {
"requestId": "req_abc123def456",
"latencyMs": 23
}
}Response Fields
| Field | Type | Description |
|---|---|---|
| success | boolean | true for successful requests |
| data.decision | string | "allow", "challenge", or "deny" |
| data.score | number | Risk score from 0 (safe) to 100 (fraud) |
| data.confidence | number | Model confidence from 0.0 to 1.0 |
| data.confidencePercent | number | Confidence as 0–100 integer |
| data.reasons | string[] | Human-readable risk factors |
| data.evidenceId | string | Evidence trail ID for forensic review |
| data.requestId | string | Unique ID for this decision (use for feedback) |
| data.processingTimeMs | number | Server-side processing time in ms |
| meta.requestId | string | Request ID echoed back |
| meta.latencyMs | number | Total response latency in ms |
Decision Thresholds
| Score Range | Default Decision | Recommended Action |
|---|---|---|
| 0 – 30 | allow | Proceed normally |
| 31 – 70 | challenge | Request MFA or CAPTCHA |
| 71 – 100 | deny | Block the action |
These thresholds are configurable via Policies. Visit Dashboard → Policies to customize per action type.