API Integration Basics: Connect TenancyDesk to Your Stack

TenancyDesk REST API enables custom integrations, workflow automation, and data syncing with other systems.

Access Requirements

• Enterprise plan (API access is Enterprise-only)
• Settings → Integrations → API
• Generate API credentials

API Base URL:

https://api.tenancydesk.com/v1

---

Authentication

JWT Token Based:

Step 1: Get Access Token

POST /auth/token
{
  "email": "your@email.com",
  "password": "your_password"
}

Response:
{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGc...",
  "expires_in": 3600
}

Step 2: Use Token in Requests

GET /deals
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...

---

Core Endpoints

Deals:

GET    /deals              # List all deals
POST   /deals              # Create new deal
GET    /deals/{id}         # Get deal details
PATCH  /deals/{id}         # Update deal
DELETE /deals/{id}         # Delete deal

Parties (Tenants/Owners):

GET    /parties            # List contacts
POST   /parties            # Create contact
GET    /parties/{id}       # Get contact

Documents:

GET    /documents          # List documents
POST   /documents          # Upload document
GET    /documents/{id}     # Download document

---

Example: Create Deal

POST /deals
Content-Type: application/json
Authorization: Bearer {token}

{
  "property_address": "Marina Heights Tower, Unit 1205",
  "annual_rent": 95000,
  "start_date": "2026-01-01",
  "duration_months": 12,
  "number_of_cheques": 4,
  "tenant": {
    "name": "Omar Khalid",
    "emirates_id": "784-2025-1234567-8",
    "mobile": "+971501234567"
  },
  "owner": {
    "name": "Sarah Johnson",
    "emirates_id": "784-2020-9876543-2"
  }
}

Response 201:
{
  "id": "deal-uuid-here",
  "status": "draft",
  "created_at": "2025-12-28T10:30:00Z"
}

---

Webhooks

Subscribe to Events:

• deal.created
• deal.updated
• document.uploaded
• payment.due
• ejari.completed

Configure: Settings → Integrations → Webhooks → Add Endpoint

Your Server Receives:

{
  "event": "payment.due",
  "timestamp": "2026-01-01T00:00:00Z",
  "data": {
    "deal_id": "deal-uuid",
    "amount": 23750,
    "due_date": "2026-01-01"
  }
}

---

Rate Limits

• Enterprise: 300 requests/minute (API access is Enterprise-only)

Best Practice: Use webhooks instead of polling

---

Use Cases

1. Accounting Sync: Push deals to QuickBooks/Xero
2. CRM Integration: Sync contacts to Salesforce
3. Custom Reports: Pull data for BI tools
4. Workflow Automation: Trigger actions in Zapier/Make

---

Documentation

Full API docs: https://docs.tenancydesk.com/api

• Interactive Swagger UI
• Code examples (cURL, JavaScript, Python)
• Postman collection

---

Next Steps

1. Generate API credentials
2. Test with Postman collection
3. Build first integration
4. Set up webhooks for real-time events