API Documentation

Complete REST API reference for SafeBet IQ Connect integration

Getting Started

Authentication and base configuration

REST API

Base URL

https://api.safeplay.ai/v1

Authentication

All requests require a Bearer token in the Authorization header:

Authorization: Bearer sk_prod_your_api_key_here
API Keys: Obtain your API keys from the Casino Dashboard Settings tab. Keep them secure and never expose them in client-side code.

POST /players/sync

Submit real-time player activity data

Request Body

{
  "player_id": "PLR-9381",
  "session_id": "SES-2024-001",
  "timestamp": "2024-11-25T14:30:00Z",
  "game_type": "blackjack",
  "bet_amount": 1100,
  "win_amount": 0,
  "session_duration_minutes": 120,
  "total_wagered": 45000,
  "total_wins": 18000,
  "total_losses": 27000,
  "bet_frequency": 8.5,
  "player_metadata": {
    "email": "player@example.com",
    "phone": "+27821234567",
    "join_date": "2024-01-15"
  }
}

Response

{
  "success": true,
  "player_id": "PLR-9381",
  "risk_score": 87,
  "risk_level": "high",
  "recommendation": "intervention_suggested",
  "triggers": [
    "extended_session_duration",
    "increasing_bet_pattern",
    "loss_chasing_behavior"
  ],
  "intervention": {
    "required": true,
    "type": "immediate",
    "channels": ["whatsapp", "email"],
    "message_template": "high_risk_alert"
  }
}

POST /players/batch-sync

Sync multiple players at once (up to 100 per request)

Request Body

{
  "players": [
    {
      "player_id": "PLR-9381",
      "session_duration_minutes": 120,
      "bet_amount": 1100,
      "total_wagered": 45000
    },
    {
      "player_id": "PLR-9382",
      "session_duration_minutes": 45,
      "bet_amount": 250,
      "total_wagered": 8500
    }
  ]
}

Response

{
  "success": true,
  "processed": 2,
  "results": [
    {
      "player_id": "PLR-9381",
      "risk_score": 87,
      "risk_level": "high"
    },
    {
      "player_id": "PLR-9382",
      "risk_score": 34,
      "risk_level": "low"
    }
  ]
}

GET /players/:player_id/risk

Retrieve current risk assessment for a player

Request

GET /players/PLR-9381/risk

Response

{
  "player_id": "PLR-9381",
  "risk_score": 87,
  "risk_level": "high",
  "last_updated": "2024-11-25T14:32:15Z",
  "session_metrics": {
    "duration_minutes": 120,
    "total_wagered": 45000,
    "win_loss_ratio": 0.67
  },
  "historical_trend": "increasing",
  "interventions_sent": 2
}

Webhooks

Receive real-time notifications when risk thresholds are exceeded

Configure Webhook Endpoint

Set up your webhook URL in the Casino Dashboard Settings. SafePlay will POST to your endpoint when:

  • Player risk score exceeds threshold (default: 85)
  • Critical risk pattern detected
  • Intervention is automatically triggered

Webhook Payload

{
  "event_type": "risk_threshold_exceeded",
  "timestamp": "2024-11-25T14:35:00Z",
  "player_id": "PLR-9381",
  "risk_score": 92,
  "risk_level": "critical",
  "triggers": ["rapid_loss_increase", "extended_session"],
  "recommended_action": "immediate_intervention"
}
Webhook Security: All webhook requests include an HMAC signature in the X-SafePlay-Signature header. Verify this signature using your webhook secret.

Rate Limits & Best Practices

Rate Limits

  • • Standard: 1,000 requests/minute
  • • Batch: 100 requests/minute
  • • Webhooks: No limit (we call you)

Best Practices

  • • Use batch endpoints for bulk syncs
  • • Cache risk scores (TTL: 60s)
  • • Implement exponential backoff

Error Codes

200Success
400Bad Request - Invalid parameters
401Unauthorized - Invalid API key
429Too Many Requests - Rate limit exceeded
500Server Error - Contact support