recommend() — Smart Provider Routing

Get an intelligent recommendation for which provider to use for a service category, based on your actual performance data.

Related: Your backup didn’t save you — you switched too late — a real-world angle on choosing a path under load.

Usage

// Laravel
use OutboundIQ\Laravel\Facades\OutboundIQ;

$decision = OutboundIQ::recommend('Payment Processing');

// PHP
$decision = $client->recommend('Payment Processing');

// Node.js / JavaScript
const decision = await outboundiq.recommend('Payment Processing');

Parameters

Parameter	Type	Description
`serviceName`	string	The service name for your project (matches `services.name` in the dashboard — e.g. 'Payment Processing'). Must be URL-encoded in HTTP paths.
`options`	array (optional)	Additional options like request_id

Response Structure

{
  "meta": {
    "version": "1.0",
    "generated_at": "2024-01-08T10:30:00Z"
  },
  "decision": {
    "use": "stripe",                    // Provider slug to use
    "confidence": 0.94,                 // 0-1 confidence score
    "confidence_label": "very_high",    // "very_high" | "high" | "medium" | "low"
    "action": "proceed",                // "proceed" | "caution" | "avoid" | "unavailable"
    "reason": "Best performance: 99.8% success rate, 245ms avg latency"
  },
  "recommendation": {
    "provider": {
      "name": "Stripe",
      "slug": "stripe",
      "logo": "https://..."
    },
    "endpoint": {
      "id": 123,
      "url_pattern": "POST /v1/charges",
      "http_method": "POST"
    },
    "score": 0.94,
    "metrics": {
      "success_rate": 99.8,
      "avg_latency_ms": 245,
      "total_requests": 12847,
      "schema_stability": 100
    },
    "status": {
      "current": "operational",
      "indicator": "green",
      "has_active_incidents": false,
      "last_incident": null
    }
  },
  "alternatives": [
    {
      "rank": 2,
      "provider": { "name": "Paystack", "slug": "paystack" },
      "score": 0.87,
      "gap": 0.07,
      "metrics": {
        "success_rate": 98.2,
        "avg_latency_ms": 380
      },
      "status": { "current": "operational" },
      "tradeoffs": ["Higher latency (380ms vs 245ms)"]
    }
  ]
}

Complete Example

use OutboundIQ\Laravel\Facades\OutboundIQ;

public function processPayment(Order $order)
{
    $decision = OutboundIQ::recommend('Payment Processing');
    
    // Handle OutboundIQ unavailable
    if (!$decision) {
        return $this->chargeWith('stripe', $order); // Default fallback
    }
    
    $action = $decision['decision']['action'];
    $provider = $decision['decision']['use'];
    
    match($action) {
        'proceed' => $this->chargeWith($provider, $order),
        'caution' => $this->chargeWithRetry($provider, $order, attempts: 3),
        'avoid' => $this->chargeWith($decision['alternatives'][0]['provider']['slug'], $order),
        default => $this->chargeWith('stripe', $order),
    };
}