Build powerful integrations.
Complete REST API documentation for sending conversion events, managing leads, and accessing analytics data programmatically.
Authentication
All API requests require authentication using your account's API key. Include the key in the Authorization header.
curl -X POST https://api.dealoracle.io/v1/events \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"event_name": "Lead", "email": "[email protected]"}'Keep your API key secure
Never expose your API key in client-side code. Use environment variables and server-side requests only.
Base URL
https://api.dealoracle.io/v1Endpoints
POST/events
Send a conversion event to all connected ad platforms (Facebook, Google, TikTok).
Request Body
{
"event_name": "Lead", // Required: Lead, Purchase, Subscribe, etc.
"event_time": 1706400000, // Optional: Unix timestamp (defaults to now)
"email": "[email protected]", // Required: User email (will be hashed)
"phone": "+1234567890", // Optional: User phone (will be hashed)
"first_name": "John", // Optional: First name (will be hashed)
"last_name": "Doe", // Optional: Last name (will be hashed)
"fbc": "fb.1.1234.5678", // Optional: Facebook Click ID
"fbp": "fb.1.1234.5678", // Optional: Facebook Browser ID
"gclid": "CjwKCAjw...", // Optional: Google Click ID
"ttclid": "ttclid_123...", // Optional: TikTok Click ID
"value": 1500.00, // Optional: Conversion value
"currency": "USD", // Optional: Currency code (default: USD)
"client_ip": "192.168.1.1", // Optional: User's IP address
"user_agent": "Mozilla/5.0..." // Optional: User's browser agent
}Response
{
"success": true,
"event_id": "evt_abc123xyz",
"platforms": {
"facebook": { "status": "sent", "match_quality": 0.95 },
"google": { "status": "sent", "match_quality": 0.92 },
"tiktok": { "status": "skipped", "reason": "no_click_id" }
}
}POST/events/batch
Send multiple conversion events in a single request. Maximum 1,000 events per batch.
Request Body
{
"events": [
{
"event_name": "Lead",
"email": "[email protected]",
"fbc": "fb.1.1234.5678"
},
{
"event_name": "Purchase",
"email": "[email protected]",
"value": 299.00,
"gclid": "CjwKCAjw..."
}
]
}GET/events/{event_id}
Retrieve details about a specific conversion event including platform delivery status.
Response
{
"event_id": "evt_abc123xyz",
"event_name": "Lead",
"created_at": "2024-01-15T10:30:00Z",
"platforms": {
"facebook": {
"status": "delivered",
"delivered_at": "2024-01-15T10:30:01Z",
"match_quality": 0.95
},
"google": {
"status": "delivered",
"delivered_at": "2024-01-15T10:30:02Z"
}
}
}Error Codes
| 400 | Bad Request | Invalid request body or parameters |
| 401 | Unauthorized | Missing or invalid API key |
| 403 | Forbidden | Insufficient permissions or plan limits exceeded |
| 404 | Not Found | Resource not found |
| 429 | Too Many Requests | Rate limit exceeded (1000 req/min) |
| 500 | Internal Server Error | Server error, please retry |
Rate Limits
Starter
API Rate100 req/min
Events1,000/mo
Growth
API Rate500 req/min
Events10,000/mo
Agency
API Rate2,000 req/min
EventsUnlimited