Leads Management

Create and manage leads in the Sakneen system using the Leads API.

Overview

The Leads API allows you to submit leads (potential customers) into the Sakneen system. This is essential for real estate companies, property developers, and lead generation systems that need to integrate with Sakneen's CRM functionality.

Endpoint

POST /external/apis/v1.0/leads

Authentication

All requests require a valid API key. The API key must be configured with allowExternal: true permission to access these endpoints.

Include your API key in the request header:

api-key: YOUR_API_KEY

Request Body Schema

Required Fields

Field	Type	Description	Validation
name	string	Full name of the lead	Required, non-empty string
phoneNumber	string	Phone number of the lead	Required, non-empty string

Optional Fields

Field	Type	Description	Validation
email	string	Email address of the lead	Optional, valid email format when provided
project	string	Project name the lead is interested in	Optional, non-empty string

Additional Headers

Header	Type	Description
language	string	Language preference for processing (e.g., 'en', 'ar')

Request Examples

Basic Lead Creation

curl -X POST "https://your-domain/external/apis/v1.0/leads" \
  -H "api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -H "language: en" \
  -d '{
    "name": "John Doe",
    "phoneNumber": "+1234567890"
  }'

Complete Lead with All Fields

curl -X POST "https://your-domain/external/apis/v1.0/leads" \
  -H "api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -H "language: en" \
  -d '{
    "name": "Jane Smith",
    "phoneNumber": "+1234567890",
    "email": "[email protected]",
    "project": "Downtown Tower"
  }'

Code Examples

JavaScript/Node.js

const apiKey = process.env.SAKNEEN_API_KEY;
const baseDomain = process.env.SAKNEEN_DOMAIN;

async function createLead(leadData) {
  const response = await fetch(`https://${baseDomain}/external/apis/v1.0/leads`, {
    method: 'POST',
    headers: {
      'api-key': apiKey,
      'Content-Type': 'application/json',
      'language': 'en'
    },
    body: JSON.stringify(leadData)
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  return await response.json();
}

// Usage
const leadData = {
  name: 'John Doe',
  phoneNumber: '+1234567890',
  email: '[email protected]',
  project: 'Downtown Tower'
};

createLead(leadData)
  .then(result => console.log('Lead created:', result))
  .catch(error => console.error('Error creating lead:', error));

Python

import os
import requests

api_key = os.getenv('SAKNEEN_API_KEY')
base_domain = os.getenv('SAKNEEN_DOMAIN')

def create_lead(lead_data):
    headers = {
        'api-key': api_key,
        'Content-Type': 'application/json',
        'language': 'en'
    }
    
    response = requests.post(
        f'https://{base_domain}/external/apis/v1.0/leads',
        json=lead_data,
        headers=headers
    )
    
    response.raise_for_status()
    return response.json()

# Usage
lead_data = {
    'name': 'John Doe',
    'phoneNumber': '+1234567890',
    'email': '[email protected]',
    'project': 'Downtown Tower'
}

try:
    result = create_lead(lead_data)
    print('Lead created:', result)
except requests.exceptions.RequestException as e:
    print('Error creating lead:', e)

PHP

<?php
$apiKey = getenv('SAKNEEN_API_KEY');
$baseDomain = getenv('SAKNEEN_DOMAIN');

function createLead($leadData) {
    global $apiKey, $baseDomain;
    
    $ch = curl_init();
    
    curl_setopt($ch, CURLOPT_URL, "https://{$baseDomain}/external/apis/v1.0/leads");
    curl_setopt($ch, CURLOPT_POST, 1);
    curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($leadData));
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'api-key: ' . $apiKey,
        'Content-Type: application/json',
        'language: en'
    ]);
    
    $response = curl_exec($ch);
    $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    
    if ($httpCode !== 200) {
        throw new Exception("HTTP error! status: {$httpCode}");
    }
    
    return json_decode($response, true);
}

// Usage
$leadData = [
    'name' => 'John Doe',
    'phoneNumber' => '+1234567890',
    'email' => '[email protected]',
    'project' => 'Downtown Tower'
];

try {
    $result = createLead($leadData);
    echo 'Lead created: ' . json_encode($result);
} catch (Exception $e) {
    echo 'Error creating lead: ' . $e->getMessage();
}
?>

Response Format

Success Response

{
  "newLead": {
    "_id": "64f1234567890abcdef123456",
    "leadId": 1001,
    "clientId": "64f1234567890abcdef123457",
    "organizationId": "64f1234567890abcdef123458",
    "compoundsIds": ["64f1234567890abcdef123459"],
    "data": {
      "name": "John Doe",
      "phoneNumber": "+1234567890",
      "email": "[email protected]",
      "project": "Downtown Tower"
    },
    "assignedAt": "2024-08-07T10:30:00.000Z",
    "isActive": true,
    "isFresh": false,
    "createdAt": "2024-08-07T10:30:00.000Z",
    "updatedAt": "2024-08-07T10:30:00.000Z"
  }
}

Functionality Features

Automatic Processing

When a lead is created, the system automatically:

1. Form Validation: Validates against the organization's public lead form configuration
2. Phone Number Validation: Checks phone number format and duplication rules
3. Project Matching: Searches for compounds matching the project name (case-insensitive regex)
4. Client Management: Creates or updates the client record associated with the lead
5. Lead Assignment: Automatically assigns the lead based on organization rules
6. Lead Hierarchy: Manages parent-child lead relationships for existing clients
7. Change Logging: Records all changes for audit and tracking purposes

Lead ID Generation

Each lead receives:

• A unique MongoDB _id
• A sequential leadId number per organization
• Association with a clientId for contact management

Error Handling

Common Error Responses

Missing API Key

{
  "statusCode": 401,
  "message": "Access Denied, API key not provided"
}

Invalid API Key

{
  "statusCode": 401,
  "message": "Access Denied, API key not valid"
}

Validation Errors

{
  "statusCode": 400,
  "message": [
    {
      "name": "name field is missing from body"
    },
    {
      "phoneNumber": "phoneNumber field is missing from body"
    }
  ]
}

Phone Number Validation Error

{
  "statusCode": 400,
  "message": [
    "Invalid phone number format",
    "Phone number already exists for this organization"
  ]
}

Missing Public Form Configuration

{
  "statusCode": 400,
  "message": "Public create lead form not found"
}

Best Practices

Data Quality

• Validate phone numbers before sending to ensure proper formatting
• Use consistent naming for projects to improve compound matching
• Include email when available for better lead management

Error Handling

• Implement retry logic for temporary network issues
• Log failed requests for debugging and monitoring
• Validate required fields before making API calls

Security

• Store API keys securely using environment variables
• Use HTTPS in production environments
• Rotate API keys regularly for security

Performance

• Batch similar requests when possible
• Implement proper timeout handling
• Monitor API response times and error rates

Integration Tips

• Test with different lead scenarios during development
• Handle duplicate detection gracefully
• Monitor lead assignment to ensure proper distribution
• Use the language header for proper localization

Local Development

For local development and testing:

curl -X POST "http://localhost:8080/external/apis/v1.0/leads" \
  -H "api-key: your-development-api-key" \
  -H "Content-Type: application/json" \
  -H "language: en" \
  -d '{
    "name": "Test Lead",
    "phoneNumber": "+1234567890",
    "email": "[email protected]",
    "project": "Test Project"
  }'

Make sure your development environment has:

• A valid API key configured with allowExternal: true
• Proper organization setup with lead form configuration
• Database connectivity for lead and client management