API Documentation

Welcome to the Genesis Fortune API documentation. Our RESTful API allows you to integrate Genesis Fortune's powerful real estate platform features into your own applications.

API Overview

The Genesis Fortune API provides programmatic access to:

• Property Management: Create, read, update, and delete property listings
• Lead Management: Access leads, update status, and track scoring
• Tenant Management: Manage tenants and rent payments
• Payment Processing: Initiate and track M-Pesa payments
• AI Chat: Integrate conversational property search
• Financial Reports: Generate and retrieve reports
• Notifications: Send and manage notifications
• Usage Tracking: Monitor API usage and feature consumption

Getting Started

Prerequisites

• Account: Active Genesis Fortune account
• Plan: MyGF 1.3 or higher (API access not available on Free/Basic)
• API Key: Generate from Settings → API Keys

Base URL

Production: https://api.mygenesisfortune.com/api
Sandbox: https://sandbox-api.mygenesisfortune.com/api

Authentication

Genesis Fortune API uses JWT (JSON Web Tokens) for authentication.

Step 1: Login to Get Token

POST /auth/login

Request:

{
  "email": "your-email@example.com",
  "password": "your-password"
}

Response:

{
  "success": true,
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "user_id",
    "email": "your-email@example.com",
    "role": "agent"
  }
}

Step 2: Include Token in Requests

Add the token to the Authorization header:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Step 3: Refresh Token When Expired

Tokens expire after 24 hours. Use the refresh token to get a new access token:

POST /auth/refresh-token

Request:

{
  "refreshToken": "your-refresh-token"
}

Quick Example

Here's a complete example of fetching properties:

// Login
const loginResponse = await fetch('https://api.mygenesisfortune.com/api/auth/login', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: 'agent@example.com',
    password: 'SecurePassword123!'
  })
});

const { token } = await loginResponse.json();

// Fetch properties
const propertiesResponse = await fetch('https://api.mygenesisfortune.com/api/properties', {
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json'
  }
});

const properties = await propertiesResponse.json();
console.log(properties);

API Endpoints Overview

Authentication

• POST /auth/register - Create new account
• POST /auth/login - Authenticate user
• POST /auth/logout - Invalidate token
• POST /auth/refresh-token - Get new access token
• POST /auth/forgot-password - Request password reset
• POST /auth/reset-password - Reset password

Properties

• GET /properties - List all properties
• GET /properties/:id - Get property details
• POST /properties - Create new property
• PUT /properties/:id - Update property
• DELETE /properties/:id - Delete property
• POST /properties/smart-query - AI-powered property search

Leads

• GET /leads - List user's leads
• GET /leads/:id - Get lead details
• POST /leads - Create new lead
• PUT /leads/:id - Update lead status
• DELETE /leads/:id - Delete lead
• GET /leads/:id/score - Get lead score breakdown
• POST /leads/:id/followup - Trigger manual follow-up

Tenants

• GET /tenants - List tenants
• GET /tenants/:id - Get tenant details
• POST /tenants - Add new tenant
• PUT /tenants/:id - Update tenant
• DELETE /tenants/:id - Remove tenant
• GET /tenants/:id/payments - Get payment history

Payments

• POST /payments/mpesa/initiate - Initiate M-Pesa payment
• GET /payments/:id/status - Check payment status
• GET /payments/history - Get payment history
• POST /payments/webhook - M-Pesa callback (internal)

Financial Reports

• POST /financial-reports/generate - Generate new report
• GET /financial-reports/:id - Get report details
• GET /financial-reports/:id/export - Download Excel export
• GET /financial-reports - List all reports

AI Chat

• POST /ai-chat/query - Send property search query
• GET /ai-chat/history - Get chat history
• DELETE /ai-chat/:sessionId - Clear chat session

Notifications

• GET /notifications - List notifications
• PUT /notifications/:id/read - Mark as read
• POST /notifications/send - Send custom notification (admin)
• DELETE /notifications/:id - Delete notification

Usage Tracking

• GET /usage/current - Get current month usage
• GET /usage/history - Get usage history
• GET /usage/limits - Get plan limits

Users

• GET /users/profile - Get user profile
• PUT /users/profile - Update profile
• POST /users/verify-email - Verify email address
• POST /users/verify-phone - Verify phone number

Response Format

All API responses follow this standard format:

Success Response

{
  "success": true,
  "data": {
    // Response data here
  },
  "message": "Operation successful"
}

Error Response

{
  "success": false,
  "message": "Error description",
  "error": {
    "code": "ERROR_CODE",
    "details": "Additional error information"
  }
}

Common HTTP Status Codes

Code	Meaning	Description
200	OK	Request successful
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Insufficient permissions
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error

Rate Limiting

API requests are rate-limited based on your subscription plan:

Plan	Requests per Hour	Requests per Day
MyGF 1.3	1,000	10,000
MyGF 3.2	Unlimited	Unlimited

Rate Limit Headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1640995200

When rate limited, you'll receive:

{
  "success": false,
  "message": "Rate limit exceeded",
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "retryAfter": 3600
  }
}

Pagination

List endpoints support pagination:

Request:

GET /properties?page=2&limit=20

Response:

{
  "success": true,
  "data": {
    "items": [ /* array of properties */ ],
    "pagination": {
      "currentPage": 2,
      "totalPages": 10,
      "totalItems": 200,
      "itemsPerPage": 20,
      "hasNext": true,
      "hasPrevious": true
    }
  }
}

Filtering and Sorting

Many endpoints support filtering and sorting:

Example:

GET /properties?type=apartment&city=Nairobi&bedrooms=3&sort=-price&status=available

Parameters:

• type: Filter by property type
• city: Filter by city
• bedrooms: Minimum bedrooms
• sort: Sort field (prefix with - for descending)
• status: Filter by availability status

Webhooks

Subscribe to real-time events:

Available Events

• lead.created - New lead received
• payment.completed - Payment successful
• tenant.rent_due - Rent due reminder
• property.viewed - Property viewed

Configuring Webhooks

POST /webhooks/subscribe

Request:

{
  "url": "https://your-app.com/webhook",
  "events": ["lead.created", "payment.completed"],
  "secret": "your-webhook-secret"
}

Webhook Payload

{
  "event": "lead.created",
  "timestamp": "2026-02-01T12:00:00Z",
  "data": {
    "leadId": "lead_123",
    "propertyId": "prop_456",
    "message": "Interested in viewing"
  },
  "signature": "sha256_signature"
}

SDK Libraries

Official SDKs coming soon for:

• JavaScript/Node.js
• Python
• PHP
• Java

For now, use standard HTTP libraries or tools like Axios, Fetch API, or Requests.

Error Codes Reference

Code	Description
AUTH_INVALID_CREDENTIALS	Wrong email or password
AUTH_TOKEN_EXPIRED	JWT token expired
AUTH_INSUFFICIENT_PERMISSIONS	User role doesn't have access
VALIDATION_ERROR	Invalid input data
RESOURCE_NOT_FOUND	Requested resource doesn't exist
RATE_LIMIT_EXCEEDED	Too many requests
PAYMENT_FAILED	M-Pesa transaction failed
USAGE_LIMIT_EXCEEDED	Monthly plan limit reached
FEATURE_NOT_AVAILABLE	Feature not in current plan

Best Practices

1. Cache Responses

Cache frequently accessed data to reduce API calls:

// Cache for 5 minutes
const cache = new Map();
const TTL = 5 * 60 * 1000;

async function getProperties() {
  const cached = cache.get('properties');
  if (cached && Date.now() - cached.timestamp < TTL) {
    return cached.data;
  }

  const data = await fetchProperties();
  cache.set('properties', { data, timestamp: Date.now() });
  return data;
}

2. Handle Rate Limits

Implement exponential backoff:

async function apiRequest(url, options, retries = 3) {
  try {
    const response = await fetch(url, options);
    if (response.status === 429 && retries > 0) {
      const retryAfter = response.headers.get('X-RateLimit-Reset');
      await sleep(retryAfter * 1000);
      return apiRequest(url, options, retries - 1);
    }
    return response;
  } catch (error) {
    if (retries > 0) {
      await sleep(1000 * (4 - retries));
      return apiRequest(url, options, retries - 1);
    }
    throw error;
  }
}

3. Secure Your API Keys

• Never commit API keys to version control
• Use environment variables
• Rotate keys regularly
• Use different keys for development/production

4. Validate Input

Always validate data before sending to API:

function validateProperty(property) {
  if (!property.title || property.title.length < 10) {
    throw new Error('Title must be at least 10 characters');
  }
  if (!property.price || property.price <= 0) {
    throw new Error('Price must be positive');
  }
  // More validations...
}

5. Handle Errors Gracefully

try {
  const response = await api.getProperties();
  return response.data;
} catch (error) {
  if (error.code === 'AUTH_TOKEN_EXPIRED') {
    await refreshToken();
    return api.getProperties(); // Retry
  }

  if (error.code === 'RATE_LIMIT_EXCEEDED') {
    showMessage('Too many requests, please try again later');
    return null;
  }

  // Log unexpected errors
  logger.error('API Error:', error);
  showMessage('An error occurred, please try again');
}

Testing

Sandbox Environment

Use the sandbox environment for testing:

https://sandbox-api.mygenesisfortune.com/api

Sandbox Features:

• No real payments processed
• Unlimited API calls (no rate limiting)
• Test data automatically cleared every 24 hours
• Same API structure as production

Test Credentials

Email: test@example.com
Password: TestPassword123!

Test M-Pesa Number

Phone: +254700000000
PIN: 1234

API Status

Check API status and uptime:

• Status Page: status.mygenesisfortune.com (coming soon)
• Twitter: @GenesisFortune for real-time updates

Getting Help

• API Documentation: This site
• Email Support: api-support@mygenesisfortune.com
• Developer Community: community.mygenesisfortune.com (coming soon)
• GitHub Issues: For SDK and integration issues

Next Steps

1. Authentication Guide - Detailed auth implementation
2. Properties API - Property management endpoints
3. Leads API - Lead management
4. Payments API - M-Pesa integration

---

API documentation is continuously updated. Last updated: February 1, 2026