Skip to main content

API Reference

For detailed API documentation with interactive examples, please visit our dedicated API Reference page.

External API Overview​

The Sakneen External API provides a comprehensive set of endpoints for integrating with the Sakneen property management system. These APIs are designed for developers to seamlessly connect their applications, websites, and systems with Sakneen's platform.

API Version: v1.0​

All external endpoints are versioned and follow the pattern: /external/apis/v1.0/

Available Endpoints​

Health Monitoring​

  • GET /external/apis/v1.0/healthz - Check API health status and version information

Leads Management​

  • POST /external/apis/v1.0/leads - Create a new lead in the CRM system

Units Management​

  • POST /external/apis/v1.0/units - Create or update property units with comprehensive details

Integration Webhooks​

  • POST /integrations/vtiger/webhook - VTiger CRM webhook endpoint for receiving updates

Authentication​

All external API requests require authentication using an API key with allowExternal: true permission. The API key must be provided in the request headers:

api-key: your-api-key-here
Content-Type: application/json
language: en

Security Features​

  • Public API Key Guard: All external endpoints are protected by the ExternalAccessApiKeyGuard
  • Organization Context: API keys are linked to specific organizations
  • Permission Control: Only API keys with external access are allowed
  • Request Validation: Comprehensive input validation on all endpoints

Error Handling​

The API returns standard HTTP status codes with detailed error messages:

  • 200 - Success
  • 201 - Created
  • 204 - No Content (for webhooks)
  • 400 - Bad Request (validation errors, missing fields)
  • 401 - Unauthorized (invalid API key, access denied)
  • 404 - Not Found
  • 500 - Internal Server Error

Common Error Responses​

Authentication Errors​

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

Validation Errors​

{
  "statusCode": 400,
  "message": [
    {
      "field": "field description"
    }
  ]
}

Request/Response Format​

Content Type​

All requests and responses use application/json content type.

Language Support​

Include the language header for proper localization:

  • en - English
  • ar - Arabic

Request Headers​

api-key: your-api-key-here
Content-Type: application/json
language: en

Rate Limiting​

API requests are subject to rate limiting to ensure fair usage across all clients. Please implement appropriate retry logic in your applications.

Data Processing Features​

Automatic Processing​

The external APIs provide intelligent data processing:

  • Lead Management: Automatic client creation, lead assignment, and CRM integration
  • Unit Management: Property synchronization, change tracking, and notification systems
  • Form Validation: Dynamic validation based on organization-specific form configurations
  • Change Logging: Comprehensive audit trails for all data modifications

Integration Capabilities​

  • CRM Integration: Seamless integration with VTiger, Salesforce, and SAP CRM systems
  • Real-time Notifications: Automatic notifications and webhook support
  • Background Processing: Asynchronous processing for heavy operations
  • Multi-tenant Support: Organization-specific data isolation and configuration

Best Practices​

Security​

  • Store API keys securely using environment variables
  • Use HTTPS in production environments
  • Rotate API keys regularly
  • Never expose API keys in client-side code

Error Handling​

  • Implement comprehensive error handling for all scenarios
  • Use exponential backoff for retry logic
  • Log API responses for debugging and monitoring
  • Validate data before sending requests

Performance​

  • Use appropriate timeout values
  • Implement request batching where possible
  • Monitor API response times and error rates
  • Cache responses when appropriate

Data Quality​

  • Validate phone numbers and email addresses before submission
  • Use consistent naming conventions for projects and properties
  • Include all available data fields for better processing
  • Follow the documented data formats and constraints