API Reference

Complete API documentation for the Esto platform

API Reference

The Esto platform provides a comprehensive REST API for managing real estate operations. All endpoints are served through the API Gateway at http://localhost:8000.

🔐 Authentication

All API endpoints require authentication. Include your API key in the request headers:

Authorization: Bearer YOUR_API_KEY

📞 Contact Management API

Create Contact

Endpoint: POST /contacts

Creates a new contact with detailed preferences and requirements.

Request Body:

{
  "email": "client@example.com",
  "fullName": "Ahmed Benali",
  "phone": "+213 123 456 789",
  "age": 35,
  "familySituation": "married",
  "children": 2,
  "wilaya": "Alger",
  "baladiya": "Hydra",
  "minBudgets": [50000000, 80000000],
  "maxBudgets": [70000000, 100000000],
  "minSurface": [80, 120],
  "maxSurface": [100, 150],
  "preferedPropertyType": "apartment",
  "bedrooms": 3,
  "options": ["parking", "elevator", "balcony"]
}

Response:

{
  "contact": {
    "id": "c_123456",
    "email": "client@example.com",
    "fullName": "Ahmed Benali",
    "phone": "+213 123 456 789",
    "age": 35,
    "familySituation": "married",
    "children": 2,
    "wilaya": "Alger",
    "baladiya": "Hydra",
    "minBudgets": [50000000, 80000000],
    "maxBudgets": [70000000, 100000000],
    "minSurface": [80, 120],
    "maxSurface": [100, 150],
    "preferedPropertyType": "apartment",
    "bedrooms": 3,
    "options": ["parking", "elevator", "balcony"],
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  "message": "Contact created successfully"
}

Create Multiple Contacts

Endpoint: POST /contacts/bulk

Creates multiple contacts in a single request for efficient batch processing.

Request Body:

{
  "contacts": [
    {
      "email": "client1@example.com",
      "fullName": "Fatima Zohra",
      "phone": "+213 123 456 790",
      "age": 28,
      "familySituation": "single",
      "wilaya": "Oran",
      "minBudgets": [30000000],
      "maxBudgets": [50000000],
      "minSurface": [60],
      "maxSurface": [90],
      "preferedPropertyType": "studio",
      "bedrooms": 1,
      "options": ["internet", "security"]
    },
    {
      "email": "client2@example.com",
      "fullName": "Karim Boudiaf",
      "phone": "+213 123 456 791",
      "age": 42,
      "familySituation": "married",
      "children": 3,
      "wilaya": "Constantine",
      "minBudgets": [80000000, 120000000],
      "maxBudgets": [100000000, 150000000],
      "minSurface": [120, 180],
      "maxSurface": [150, 200],
      "preferedPropertyType": "villa",
      "bedrooms": 4,
      "options": ["garden", "garage", "pool"]
    }
  ]
}

Response:

{
  "contacts": [
    {
      "id": "c_123457",
      "email": "client1@example.com",
      "fullName": "Fatima Zohra"
      // ... other fields
    },
    {
      "id": "c_123458",
      "email": "client2@example.com",
      "fullName": "Karim Boudiaf"
      // ... other fields
    }
  ],
  "errors": [],
  "successCount": 2,
  "errorCount": 0,
  "message": "Created 2 contacts successfully, 0 failed"
}

Get Contact

Endpoint: GET /contacts/:id

Retrieves a specific contact by ID.

Response:

{
  "contact": {
    "id": "c_123456",
    "email": "client@example.com",
    "fullName": "Ahmed Benali"
    // ... all contact fields
  },
  "message": "Contact retrieved successfully"
}

List Contacts

Endpoint: GET /contacts

Retrieves a paginated list of contacts with optional filtering.

Query Parameters:

  • page (optional): Page number (default: 1)
  • limit (optional): Items per page (default: 10)
  • search (optional): Search in name, email, or phone
  • wilaya (optional): Filter by wilaya

Example Request:

GET /contacts?page=1&limit=20&search=ahmed&wilaya=Alger

Response:

{
  "contacts": [
    {
      "id": "c_123456",
      "email": "client@example.com",
      "fullName": "Ahmed Benali"
      // ... other fields
    }
  ],
  "total": 150,
  "page": 1,
  "limit": 20,
  "totalPages": 8
}

Update Contact

Endpoint: PUT /contacts/:id

Updates an existing contact. Only provided fields will be updated.

Request Body:

{
  "fullName": "Ahmed Benali Updated",
  "phone": "+213 123 456 999",
  "maxBudgets": [80000000, 120000000],
  "options": ["parking", "elevator", "balcony", "internet"]
}

Delete Contact

Endpoint: DELETE /contacts/:id

Deletes a contact permanently.

Response:

{
  "success": true,
  "message": "Contact deleted successfully"
}

🏠 Property Management API

Create Property

Endpoint: POST /estates

Creates a new property listing.

Request Body:

{
  "title": "Modern Apartment in Hydra",
  "description": "Beautiful 3-bedroom apartment with sea view",
  "price": 75000000,
  "surface": 120,
  "bedrooms": 3,
  "bathrooms": 2,
  "propertyType": "apartment",
  "wilaya": "Alger",
  "baladiya": "Hydra",
  "images": ["https://example.com/image1.jpg", "https://example.com/image2.jpg"]
}

Response:

{
  "estate": {
    "id": "e_123456",
    "title": "Modern Apartment in Hydra",
    "description": "Beautiful 3-bedroom apartment with sea view",
    "price": 75000000,
    "surface": 120,
    "bedrooms": 3,
    "bathrooms": 2,
    "propertyType": "apartment",
    "wilaya": "Alger",
    "baladiya": "Hydra",
    "images": ["https://example.com/image1.jpg", "https://example.com/image2.jpg"],
    "createdAt": "2024-01-15T10:30:00Z",
    "updatedAt": "2024-01-15T10:30:00Z"
  },
  "message": "Property created successfully"
}

Create Multiple Properties

Endpoint: POST /estates/bulk

Creates multiple properties in a single request.

List Properties

Endpoint: GET /estates

Retrieves a paginated list of properties with optional filtering.

Query Parameters:

  • page (optional): Page number (default: 1)
  • limit (optional): Items per page (default: 10)
  • search (optional): Search in title or description
  • wilaya (optional): Filter by wilaya

Update Property

Endpoint: PUT /estates/:id

Updates an existing property listing.

Get Property

Endpoint: GET /estates/:id

Retrieves a specific property by ID.

🤖 AI Matching API

Get Property Recommendations

Endpoint: POST /matcher/match

Finds the best matching contacts for a specific property using AI algorithms.

Request Body:

{
  "property_id": "e_123456",
  "embedding": [0.1, 0.2, 0.3, ...] // Vector embedding of property
}

Response:

{
  "success": true,
  "message": "Matching completed successfully",
  "matches_found": 15,
  "matches_stored": 15,
  "recommendations": [
    {
      "contactId": "c_123456",
      "score": 0.92,
      "explanation": "Perfect match: Budget range 50M-70M matches property price 75M, location preference 'Alger' matches property location, property type 'apartment' matches preference, surface area 120sqm within preferred range 80-150sqm"
    },
    {
      "contactId": "c_123457",
      "score": 0.85,
      "explanation": "Good match: Budget and location preferences align, minor difference in surface area preference"
    }
  ]
}

Health Check

Endpoint: GET /matcher/health

Checks the health status of the matching service.

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "services": {
    "qdrant": "connected",
    "postgresql": "connected"
  }
}

🎯 Marketing API

Generate Facebook Marketing Strategy

Endpoint: POST /agents/facebook-strategy

Generates AI-powered Facebook marketing strategy for a property.

Request Body:

{
  "property_id": "e_123456"
}

Response:

{
  "strategy": {
    "target_audience": "Young professionals aged 25-35, families with children",
    "ad_format": "Carousel ads with property images",
    "budget_recommendation": "5000-10000 DZD per day",
    "creative_recommendations": [
      "Highlight sea view and modern amenities",
      "Emphasize proximity to schools and shopping centers",
      "Show floor plan and room dimensions"
    ],
    "copy_suggestions": [
      "🏠 Beautiful 3-bedroom apartment in Hydra",
      "🌊 Sea view from every room",
      "🏫 Near schools and shopping centers",
      "💰 Competitive price: 75M DZD"
    ]
  }
}

Compare Properties

Endpoint: POST /agents/compare-properties

Generates detailed comparison between two properties.

Request Body:

{
  "property1_id": "e_123456",
  "property2_id": "e_123457"
}

Response:

{
  "comparison": {
    "summary": "Property A offers better value for money with larger surface area",
    "price_analysis": "Property A: 75M DZD (625K/sq.m), Property B: 80M DZD (800K/sq.m)",
    "location_comparison": "Both in desirable areas, Property A closer to amenities",
    "features_comparison": "Property A has more bedrooms and bathrooms",
    "recommendation": "Property A is recommended for families, Property B for couples"
  }
}

📄 Document Generation API

Generate PDF Quote

Endpoint: POST /documents/quote

Generates a professional PDF quote for a property-client match.

Request Body:

{
  "property_id": "e_123456",
  "contact_id": "c_123456",
  "quote_details": {
    "valid_until": "2024-02-15",
    "special_conditions": "Subject to financing approval"
  }
}

Response:

{
  "pdf_url": "https://example.com/quotes/quote_123456.pdf",
  "message": "PDF quote generated successfully"
}

🔧 Error Handling

All API endpoints return consistent error responses:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email format",
    "details": {
      "field": "email",
      "value": "invalid-email"
    }
  }
}

Common Error Codes

  • VALIDATION_ERROR - Invalid request data
  • NOT_FOUND - Resource not found
  • CONFLICT - Resource already exists
  • UNAUTHORIZED - Authentication required
  • FORBIDDEN - Insufficient permissions
  • INTERNAL_ERROR - Server error

📊 Rate Limiting

API requests are rate-limited to ensure fair usage:

  • Standard Plan: 1000 requests per hour
  • Premium Plan: 10000 requests per hour
  • Enterprise Plan: Custom limits

Rate limit headers are included in responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1642234567

🔗 SDKs and Libraries

Official SDKs are available for popular languages:

  • JavaScript/TypeScript: npm install @esto/sdk
  • Python: pip install esto-sdk
  • Java: Available in Maven Central
  • C#: Available in NuGet

📚 Next Steps

PDF Generation

Professional PDF document generation for quotes, comparisons, and reports

Recommendation Logic

AI-powered matching algorithms and recommendation system