Skip to main content

Getting Started

Welcome to Sakneen Developer Documentation! This comprehensive guide will help you integrate with our real estate management platform in less than 5 minutes.

Overview​

Sakneen is a comprehensive, enterprise-grade platform for real estate and property management that serves developers, real estate companies, and property management organizations. Our External API provides robust integration capabilities for connecting your applications, websites, lead generation systems, and third-party tools with Sakneen's powerful platform.

Platform Capabilities​

The Sakneen platform offers extensive functionality for real estate management:

Core Features:

  • Lead Management & CRM: Comprehensive lead capture, assignment, and customer relationship management
  • Property & Unit Management: Complete property portfolio management with detailed unit information
  • Sales Operations: Advanced sales monitoring, contract management, and reservation systems
  • Multi-Channel Integration: Seamless integration with external CRM systems (VTiger, Salesforce, SAP)
  • Real-time Notifications: Automated notifications and webhook support for external systems
  • Multi-tenant Architecture: Organization-specific data isolation and configuration

Advanced Capabilities:

  • Automated Lead Assignment: Intelligent lead distribution based on organizational rules
  • Form-based Validation: Dynamic validation based on organization-specific configurations
  • Multi-language Support: Full localization support for Arabic and English
  • Audit & Change Tracking: Comprehensive logging and change management
  • Background Processing: Asynchronous processing for heavy operations
  • Analytics & Reporting: Advanced analytics and business intelligence

External API Integration​

Our External API (v1.0) is specifically designed for developers who need to:

  • Capture leads from websites, landing pages, and marketing campaigns
  • Synchronize property units from external systems and databases
  • Integrate with existing CRM and property management systems
  • Automate data flow between Sakneen and third-party applications
  • Build custom applications that leverage Sakneen's real estate expertise

What you'll need​

  • An active Sakneen organization account
  • API credentials with external access permissions
  • A development environment with HTTP client capability
  • Basic understanding of REST APIs and JSON
  • Optional: Integration with webhook endpoints for real-time updates

Quick Start​

To get started with the Sakneen External API:

1. Get Your API Credentials​

Contact our support team to obtain:

  • Your API key with allowExternal: true permission
  • Your assigned base domain (e.g., your-organization.sakneen.com)
  • Organization-specific configuration details
  • Access to staging and production environments

Contact Information:

2. Base URLs​

All API requests should be made to your assigned domain:

Production: https://your-domain/external/apis/v1.0/
Staging:    https://your-staging-domain/external/apis/v1.0/

Available Endpoints:

  • GET /healthz - API health check and version information
  • POST /leads - Create and manage leads in the CRM system
  • POST /units - Create or update property units with comprehensive details

Note: Replace your-domain and your-staging-domain with the actual domains provided by Sakneen support.

3. Authentication & Security​

All external API endpoints are protected by the ExternalAccessApiKeyGuard which provides:

  • API Key Validation: Ensures only authorized API keys can access endpoints
  • Organization Context: Automatically associates requests with your organization
  • Permission Control: Validates that your API key has external access enabled
  • Request Security: Comprehensive input validation and sanitization

Include your API key in the request headers:

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",
    "project": "Downtown Tower",
    "email": "[email protected]"
  }'

4. Verify Your Integration​

Step 1: Health Check

First, verify your API key and connection with the health check endpoint:

curl --location "https://your-domain/external/apis/v1.0/healthz" \
  --header "api-key: your-api-key-here"

Expected Response:

{
  "description": "Backend APIs for the Sakneen platform",
  "ok": true,
  "version": "v1.0"
}

Step 2: Create a Test Lead

Test lead creation to ensure your integration is working:

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": "Test Lead",
    "phoneNumber": "+1234567890",
    "project": "Test Project",
    "email": "[email protected]"
  }'

Step 3: Test Unit Management (Optional)

If you plan to manage property units, test the units endpoint:

curl -X POST "https://your-domain/external/apis/v1.0/units" \
  -H "api-key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -H "language: en" \
  -d '{
    "recordSystemId": "TEST-001",
    "unitId": "UNIT-001",
    "price": 500000,
    "propertyType": "apartment",
    "status": "available"
  }'

Integration Features​

Automatic Processing​

When you submit data through our External API, Sakneen automatically:

For Leads:

  • Validates lead data against your organization's form configuration
  • Checks phone number format and duplication rules
  • Matches project names with your compound database
  • Creates or updates client records for contact management
  • Assigns leads based on your organization's assignment rules
  • Logs all changes for audit and compliance purposes

For Units:

  • Synchronizes property data with your existing inventory
  • Validates all property information and pricing
  • Tracks changes and maintains version history
  • Triggers background jobs for heavy processing
  • Sends notifications to relevant team members
  • Integrates with your external CRM systems automatically

Error Handling & Validation​

Our API provides comprehensive error handling:

  • Input Validation: All fields are validated according to business rules
  • Authentication Errors: Clear messages for API key issues
  • Business Logic Validation: Organization-specific validation rules
  • Detailed Error Messages: Specific information about what went wrong
  • HTTP Status Codes: Standard codes for different error types

Multi-language Support​

Include the language header for proper localization:

  • en - English (default)
  • ar - Arabic

Next Steps​

Documentation Resources​

Advanced Integration​

  • Webhook Setup: Configure webhooks for real-time updates from Sakneen
  • CRM Integration: Set up automatic synchronization with VTiger, Salesforce, or SAP
  • Custom Validation: Work with our team to configure organization-specific validation rules
  • Background Processing: Understand how to handle asynchronous operations
  • Rate Limiting: Learn about API limits and best practices

Support & Community​

  • Technical Support: [email protected]
  • Integration Assistance: Our team can help with complex integration scenarios
  • Best Practices: Regular updates on optimal integration patterns
  • API Updates: Stay informed about new features and endpoint additions

Development Environment​

For local development and testing:

  1. Use staging endpoints for development and testing
  2. Implement proper error handling from the start
  3. Test with real data scenarios to ensure robustness
  4. Monitor API responses and implement logging
  5. Follow security best practices for API key management

Start with the health check endpoint to verify your setup, then gradually implement the specific endpoints you need for your integration.