API Reference
/api/v1/decide
Full-featured fraud decision endpoint with dual-path detection, policy evaluation, and async side effects.
The primary endpoint for real-time fraud decisions. It runs a dual-path detection engine (fast path + comprehensive path), evaluates your configured policies, and triggers webhooks and audit logging asynchronously.
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",
"sessionId": "sess_abc",
"metadata": {
"flow": "password"
}
}'Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| userId | string | Yes | Your internal user identifier (max 256 chars) |
| action | string | Yes | The action being performed (login, signup, trial_start, checkout, purchase, transfer, password_change, custom) |
| string | No | User email for correlation | |
| ip | string | No | Client IP (auto-extracted from request if omitted) |
| deviceId | string | No | Device identifier (populated automatically by Browser SDK via visitorId) |
| sessionId | string | No | Session identifier for cross-request correlation |
| userAgent | string | No | Browser user agent string |
| amount | number | No | Transaction amount (for payment actions) |
| currency | string | No | ISO 4217 currency code (e.g. USD) |
| device | object | No | SDK DeviceSignals (populated automatically by Browser SDK) |
| behavior | object | No | SDK BehaviorSignals (populated automatically by Browser SDK) |
| metadata | object | No | Arbitrary key-value pairs for custom context |
Response (200 OK)
Success responsejson
{
"success": true,
"data": {
"decision": "allow",
"score": 15,
"confidence": 0.97,
"confidencePercent": 97,
"reasons": ["LOW_RISK"],
"evidenceId": "evi_xxxx",
"requestId": "req_abc123",
"processingTimeMs": 23
},
"meta": {
"requestId": "req_abc123",
"latencyMs": 23
}
}Error Responses
| Status | Code | Description |
|---|---|---|
| 400 | VALIDATION_ERROR | Missing required fields or invalid format |
| 401 | UNAUTHORIZED | Invalid or missing API key |
| 429 | RATE_LIMIT_EXCEEDED | Rate limit exceeded (see Retry-After header) |
| 500 | INTERNAL_ERROR | Server error (automatically retried) |
Side Effects
The /decide endpoint runs these operations asynchronously after returning the response (they do not add latency):
- Audit trail: Cryptographically signed audit log entry
- Webhooks: Dispatched to configured webhook endpoints
- KV persistence: Decision stored for replay protection and velocity
- Case creation: Auto-created for high-risk decisions (score ≥ 80)
- DLQ fallback: Failed background tasks are queued to a dead-letter queue for retry
Rate limit: 100 requests/minute per API key (configurable on Enterprise plans).