Table of Contents
API Overview
The Maru Lead Generation Engine provides RESTful APIs for integrating assessment tools into your applications. All endpoints return JSON responses and use standard HTTP methods.
Base URL
Production: https://your-domain.com/api
Development: http://localhost:3000/apiAPI Features
- RESTful design with standard HTTP methods
- JSON request and response format
- Rate limiting and security measures
- Comprehensive error handling
- Real-time assessment processing
Authentication
Currently, the API uses IP-based rate limiting. For production deployments, implement API key authentication:
Authentication Header
// Future implementation
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
}Endpoints
Assessment API
POST /api/assessments
Create and process a new assessment.
Request Body
{
"email": "user@example.com",
"app_type": "lead_score",
"input_data": {
"company_name": "Example Corp",
"website_url": "https://example.com",
"industry": "Technology",
"company_size": "smb"
}
}Assessment Types
lead_score- Lead Score Predictorpipeline_leak- Pipeline Leak Detectorproposal- Proposal Acceleratortech_audit- Tech Stack Auditor
Success Response (200)
{
"success": true,
"data": {
"assessment_id": "uuid-here",
"score": 75,
"factors": {
"website_quality": 80,
"tech_stack_maturity": 70,
"content_quality": 75,
"seo_readiness": 75
},
"recommendations": [
"Implement lead capture forms on key pages",
"Add clear call-to-action buttons",
"Optimize page loading speed"
]
}
}GET /api/assessments/{id}
Retrieve a specific assessment by ID.
Response
{
"success": true,
"data": {
"id": "assessment-uuid",
"lead_id": "lead-uuid",
"app_type": "lead_score",
"status": "completed",
"score": 75,
"analysis_data": { ... },
"recommendations": [ ... ],
"created_at": "2024-12-23T10:00:00Z",
"completed_at": "2024-12-23T10:01:00Z"
}
}Leads API
GET /api/leads
Retrieve leads with optional filtering and pagination.
Query Parameters
page- Page number (default: 1)limit- Results per page (default: 20, max: 100)industry- Filter by industrycompany_size- Filter by company sizemin_score- Minimum lead scorecreated_after- ISO date string
Example Request
fetch('/api/leads?industry=technology&min_score=70&limit=50')
.then(response => response.json())
.then(data => console.log(data));GET /api/leads/{id}
Retrieve a specific lead with all associated assessments.
Response
{
"success": true,
"data": {
"id": "lead-uuid",
"email": "user@example.com",
"company_name": "Example Corp",
"website_url": "https://example.com",
"industry": "Technology",
"company_size": "smb",
"lead_score": 75,
"created_at": "2024-12-23T10:00:00Z",
"assessments": [
{
"id": "assessment-uuid",
"app_type": "lead_score",
"score": 75,
"completed_at": "2024-12-23T10:01:00Z"
}
],
"activities": [
{
"activity_type": "assessment_complete",
"created_at": "2024-12-23T10:01:00Z"
}
]
}
}Analytics API
GET /api/analytics/summary
Get analytics summary for dashboard display.
Response
{
"success": true,
"data": {
"total_leads": 1250,
"total_assessments": 2100,
"conversion_rate": 0.68,
"avg_lead_score": 72.5,
"assessments_by_type": {
"lead_score": 800,
"pipeline_leak": 450,
"proposal": 350,
"tech_audit": 500
},
"leads_by_industry": {
"technology": 400,
"healthcare": 300,
"finance": 250,
"other": 300
}
}
}Error Handling
The API uses standard HTTP status codes and returns detailed error information:
HTTP Status Codes
200- Success201- Created400- Bad Request401- Unauthorized429- Rate Limited500- Server Error
Error Response Format
{
"success": false,
"error": "Validation failed",
"details": {
"email": "Invalid email format",
"website_url": "URL is required"
}
}Rate Limits
API endpoints have the following rate limits:
- Assessment API: 10 requests per minute per IP
- Leads API: 60 requests per minute per IP
- Analytics API: 30 requests per minute per IP
Rate limit headers are included in all responses:
Rate Limit Headers
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 8
X-RateLimit-Reset: 1640995200Code Examples
JavaScript/Node.js
Submit Assessment
async function submitAssessment(assessmentData) {
try {
const response = await fetch('/api/assessments', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
},
body: JSON.stringify(assessmentData)
});
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
const result = await response.json();
if (result.success) {
console.log('Assessment completed:', result.data);
return result.data;
} else {
console.error('Assessment failed:', result.error);
}
} catch (error) {
console.error('Network error:', error);
}
}Python
Fetch Leads
import requests
import json
def fetch_leads(filters=None):
url = "http://localhost:3000/api/leads"
params = filters or {}
try:
response = requests.get(url, params=params)
response.raise_for_status()
data = response.json()
if data['success']:
return data['data']
else:
print(f"API Error: {data['error']}")
return None
except requests.exceptions.RequestException as e:
print(f"Request failed: {e}")
return None
# Usage
leads = fetch_leads({
'industry': 'technology',
'min_score': 70,
'limit': 50
})cURL
Submit Assessment via cURL
curl -X POST http://localhost:3000/api/assessments \
-H "Content-Type: application/json" \
-d '{
"email": "test@example.com",
"app_type": "lead_score",
"input_data": {
"company_name": "Test Company",
"website_url": "https://test.com",
"industry": "Technology",
"company_size": "smb"
}
}'Important Notes
- Always validate input data before sending to the API
- Handle rate limiting gracefully with exponential backoff
- Store assessment IDs for future reference
- Monitor API response times and implement timeouts
SDK Development
We're working on official SDKs for popular programming languages. In the meantime, you can use the examples above or create wrapper functions for your specific use case.
Need Help?
For technical support or questions about API integration,contact our development team.
Was this article helpful?
Let us know if you found this documentation useful or if you have suggestions for improvement.