Skip to main content

​
Overview

The User Journey API tracks and validates critical steps in a user’s transaction flow through defined API checkpoints. It ensures that expected events occur in the correct sequence and flags suspicious or out-of-order behavior in real time.

​
Authentication

All endpoints require API key authentication. Header x-access-token: YOUR_API_KEY

​
Submit event

Submit a user journey event for fraud assessment.

​
Request Endpoint

POST: {{BASE_URL}}/api/v1/journey/event/
  • Media-Type: application/json

​
Payload Example Request

{
  "user_id": "string",
  "session_id": "string",
  "event": "LOGIN | OTP_VERIFY | PAYMENT_INIT | PAYMENT_COMPLETE | LOGOUT",
  "timestamp": "ISO 8601 datetime",
  "device_id": "string (optional)",
  "ip_address": "string (optional)",
  "metadata": {
    "amount": "number (optional)",
    "currency": "string (optional)"
  }
}
201 Created Response 
{
  "status": "Success",
  "data": {
    "status": "allow | block | review",
    "risk_score": 0.0-1.0,
    "reason": "string",
    "session_state": "string",
    "alert_triggered": boolean
  },
  "message": "success"
}

​
Get Session State

Retrieve the current state of a session.

​
Request Endpoint

GET: {{BASE_URL}}/api/v1/journey/session/{session_id}/

​
200 Response

{
  "status": "success",
  "data": {
    "session_id": "string",
    "user_id": "string",
    "current_state": "string",
    "events": [...],
    "start_time": "ISO 8601 datetime"
  },
  "message": "success"
}

​
Clear Session

Clear all stored data for a session.

​
Request Endpoint

DELETE: {{BASE_URL}}/api/v1/journey/session/{session_id}/

​
204 No Content Response

{
  "message": "Session cleared"
}

​
User Analytics

Retrieve fraud and risk statistics for a user.

​
Request Endpoint

GET: {{BASE_URL}}/api/v1/journey/analytics/user/{user_id}/

​
200 Response

{
  "status": "success",
  "data": {
    "user_id": "string",
    "total_events": number,
    "average_risk_score": number,
    "blocked_events": number,
    "reviewed_events": number,
    "total_sessions": number,
    "average_session_risk": number
  },
  "message": "Success"
}

​
Health check

Check service health and dependencies.

​
Request Endpoint

GET: {{BASE_URL}}/api/v1/journey/health/

​
200 Response

{
  "status": "healthy | degraded",
  "broker": "connected | disconnected",
  "database": "connected | disconnected",
  "timestamp": "ISO 8601 datetime"
}

​
Error Codes

  • 200 Success: Data retrieved successfully.
  • 201 Created: Event processed successfully.
  • 400 Bad Request: Missing, malformed, or invalid fields in the request payload.
  • 401 Unauthorized: Authentication failed or API key is missing or invalid.
  • 403 Forbidden: The authenticated client does not have permission to access this resource.
  • 404 Not Found: The requested resource or endpoint does not exist.
  • 429 Too Many Requests: Rate limit exceeded. Please retry after the specified cooldown period.
  • 500 Internal Server Error: Unexpected error during processing. The request body is not set correctly.