# AGENTS
Source: https://docs.majarrah.io/AGENTS
> **First-time setup**: Customize this file for your project. Prompt the user to customize this file for their project.
> For Mintlify product knowledge (components, configuration, writing standards),
> install the Mintlify skill: `npx skills add https://mintlify.com/docs`
# Documentation project instructions
## About this project
* This is a documentation site built on [Mintlify](https://mintlify.com)
* Pages are MDX files with YAML frontmatter
* Configuration lives in `docs.json`
* Use the Mintlify MCP server, `https://mcp.mintlify.com`, to edit content and settings via MCP
* Use the Mintlify docs MCP server, `https://www.mintlify.com/docs/mcp`, to query information about using Mintlify via MCP
## Terminology
## Style preferences
* Use active voice and second person ("you")
* Keep sentences concise — one idea per sentence
* Use sentence case for headings
* Bold for UI elements: Click **Settings**
* Code formatting for file names, commands, paths, and code references
## Content boundaries
# Authentication
Source: https://docs.majarrah.io/api-reference/authentication
All API requests require a Bearer token.
The Majarrah API is available to **broker and agency accounts only**. If you signed up as a buyer or seller, API keys are not available on your account.
## Get your API key
API keys are managed from your dashboard.
Go to **Dashboard → Settings → API Keys** at [www.majarrah.io/ar/dashboard/settings/api-keys](https://www.majarrah.io/ar/dashboard/settings/api-keys) and click **New key**. Each key is tied to your workspace's decision balance.
Keep your API key secret. Never expose it in client-side code or public repositories.
## Using your key
Pass the key as a Bearer token in the `Authorization` header on every request.
```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```
## Example
```bash theme={null}
curl -X POST https://api.majarrah.io/v1/decisions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"property": {
"type": "apartment",
"price": 850000,
"area": 95,
"bedrooms": 2,
"bathrooms": 2,
"floor": 8
},
"location": {
"city": "Al Khobar",
"district": "Al Corniche"
},
"reasoning": false
}'
```
## Decision balance
Every API key is tied to your workspace's credit balance. You can check your remaining balance in the response of any `/decisions` call via `credits_remaining`, or from **Dashboard → Settings → API Credits**.
When your balance reaches zero, all requests return `402 insufficient_decisions` until you top up.
# Book a viewing
Source: https://docs.majarrah.io/api-reference/bookings/create
POST https://api.majarrah.io/v1/bookings
Schedule a viewing for a property at one of the broker's available slots.
Creates a viewing booking. The broker is notified immediately and can confirm, propose a new time, or decline.
## Request body
The ID of the property to view.
When the viewing should happen. Must match one of the broker's available slots — check with the availability endpoint first.
Override the phone number the broker will call you on. Defaults to the phone on the buyer's profile.
Optional note visible to the broker, e.g. "coming with my wife".
## Response
Whether a lead credit was charged to the broker's workspace for this booking.
## Example
```bash theme={null}
curl https://api.majarrah.io/v1/bookings \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"property_id": "e39a8b2b-...",
"scheduled_at": "2026-09-25T18:00:00+03:00",
"notes": "Coming with my wife"
}'
```
```json theme={null}
{
"booking": {
"id": "bkg-1a2b3c...",
"property_id": "e39a8b2b-...",
"scheduled_at": "2026-09-25T18:00:00+03:00",
"status": "pending"
},
"charged": true
}
```
## Errors
* **`slot_unavailable`** — the requested time isn't a broker-open slot.
* **`slot_already_booked`** — someone else booked this slot first.
* **`property_not_found`** — the `property_id` doesn't exist or is unpublished.
* **`self_booking_forbidden`** — you can't book your own listing.
# Create a Decision
Source: https://docs.majarrah.io/api-reference/decisions/create
POST /decisions
Evaluate a property and get a structured verdict.
Not sure which city or district name to use? Use [GET /locations](https://docs.majarrah.io/api-reference/locations/search) to search by name and get the exact numeric IDs to pass here.
## Request body
The property to evaluate.
Property type. One of: `apartment`, `villa`, `land`, `commercial`, `office`
Asking price in SAR.
Total area in square meters.
Number of bedrooms.
Number of bathrooms.
Floor number. Use `0` for ground floor.
Property age in years.
Whether parking is available.
Whether the property is furnished.
Property location. Pass either numeric IDs (recommended) from [GET /locations](/api-reference/locations/search), or raw string names.
District ID from `GET /locations`. Resolves both city and district automatically — no need to pass `city_id` or strings separately.
City ID from `GET /locations`. Use alongside `district` string if you have the city ID but not the district ID.
City name string. E.g. `"Riyadh"`, `"Jeddah"`, `"Al Khobar"`. Required if not using `city_id` or `district_id`.
District or neighbourhood string. E.g. `"Al Malqa"`, `"Al Corniche"`. Required if not using `district_id`.
Latitude (optional, improves location scoring).
Longitude (optional, improves location scoring).
`false` - algorithmic scoring only (1 decision). Returns score and breakdown instantly.
`true` - scoring + AI reasoning (3 decisions). Adds a `reasoning` object with English and Arabic explanations.
***
## Response
Always `"decision"`.
`match`, `partial`, or `no_match`. Derived from `score`: 70+ is match, 40–69 is partial, below 40 is no match.
Overall score from 0 to 100.
Per-bucket scores and statuses.
`score` (0–100) and `status` (`pass`, `warn`, `fail`). Compares property price against market benchmarks.
`score` and `status`. Area demand and market trend.
`score` and `status`. Price per sqm vs. market average for the type and location.
`score` and `status`. Type-specific factors: bedrooms, floor, age, parking, etc.
Calculated price per square meter for this property.
MOJ market data used for price scoring. `null` if no benchmark exists for the given city/district.
Median transaction price per sqm (SAR) for this city/district. The midpoint — half of transactions were above, half below.
25th percentile price per sqm. Properties priced at or below this are considered well-priced.
75th percentile price per sqm. Properties priced above this are considered expensive for the area.
Year of the benchmark data (MOJ transaction year).
Number of transactions used to compute the benchmark.
Year-over-year price change percentage vs. the prior year. `null` if no prior-year data is available.
Only present when `reasoning: true`.
2–3 sentence investment rationale in English.
2–3 sentence investment rationale in Arabic.
Up to 3 positive factors supporting the verdict.
Risk factors to be aware of.
Decisions consumed by this request. `1` for scoring only, `3` for reasoning.
Your remaining decision balance after this request.
***
## Examples
```bash Apartment - scoring only theme={null}
curl -X POST https://api.majarrah.io/v1/decisions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"property": {
"type": "apartment",
"price": 850000,
"area": 95,
"bedrooms": 2,
"bathrooms": 2,
"floor": 8
},
"location": {
"city": "Al Khobar",
"district": "Al Corniche"
},
"reasoning": false
}'
```
```bash Villa - with reasoning theme={null}
curl -X POST https://api.majarrah.io/v1/decisions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"property": {
"type": "villa",
"price": 2100000,
"area": 420,
"bedrooms": 4,
"bathrooms": 5
},
"location": {
"city": "Riyadh",
"district": "Al Nakheel"
},
"reasoning": true
}'
```
```bash Land theme={null}
curl -X POST https://api.majarrah.io/v1/decisions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"property": {
"type": "land",
"price": 500000,
"area": 600
},
"location": {
"city": "Riyadh",
"district": "North Riyadh"
},
"reasoning": false
}'
```
```bash Using location IDs theme={null}
curl -X POST https://api.majarrah.io/v1/decisions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"property": {
"type": "apartment",
"price": 850000,
"area": 95,
"bedrooms": 2,
"bathrooms": 2
},
"location": {
"district_id": 23741856
},
"reasoning": false
}'
```
```json 200 - reasoning: false theme={null}
{
"object": "decision",
"verdict": "match",
"score": 76,
"breakdown": {
"price": { "score": 85, "status": "pass" },
"location": { "score": 90, "status": "pass" },
"size": { "score": 82, "status": "pass" },
"details": { "score": 65, "status": "warn" }
},
"price_per_sqm": 8947,
"benchmark": {
"median_sqm": 9100,
"p25_sqm": 8200,
"p75_sqm": 10500,
"year": 2025,
"transaction_count": 143,
"yoy_pct": 4
},
"credits_used": 1,
"credits_remaining": 99
}
```
```json 200 - reasoning: true theme={null}
{
"object": "decision",
"verdict": "match",
"score": 76,
"breakdown": {
"price": { "score": 85, "status": "pass" },
"location": { "score": 90, "status": "pass" },
"size": { "score": 82, "status": "pass" },
"details": { "score": 65, "status": "warn" }
},
"price_per_sqm": 8947,
"benchmark": {
"median_sqm": 9100,
"p25_sqm": 8200,
"p75_sqm": 10500,
"year": 2025,
"transaction_count": 143,
"yoy_pct": 4
},
"reasoning": {
"reasoning_en": "Strong fit overall. Priced 2% below the Al Corniche median of 9,100 SAR/sqm. The Al Khobar corniche commands consistent demand and saw 4% YoY price growth in 2025. Two bedrooms at 95 sqm is above the area median for this price bracket.",
"reasoning_ar": "مطابقة قوية بشكل عام. السعر أقل بنسبة 2% من متوسط الكورنيش البالغ 9,100 ريال/م². يشهد كورنيش الخبر طلباً ثابتاً وارتفع سعره 4% سنوياً في 2025. غرفتان على 95م² تفوق متوسط المنطقة في هذه الفئة السعرية.",
"key_factors": ["Priced below area median", "Strong YoY price growth", "High-demand location"],
"risk_flags": ["Limited transaction count in district"]
},
"credits_used": 3,
"credits_remaining": 97
}
```
```json 401 - Invalid API key theme={null}
{
"error": "invalid_api_key",
"message": "Provide a valid Bearer token. API keys start with sk- and can be created in your dashboard."
}
```
```json 402 - Insufficient decisions theme={null}
{
"error": "insufficient_decisions",
"message": "This request requires 3 decisions. Your workspace has 1. Purchase more at www.majarrah.io.",
"required": 3,
"balance": 1
}
```
```json 422 - Validation error theme={null}
{
"error": "validation_error",
"message": "property.area must be a positive number (sqm).",
"field": "property.area"
}
```
# Errors
Source: https://docs.majarrah.io/api-reference/errors
All errors follow a consistent shape with a machine-readable code and a human-readable message.
## Error shape
```json theme={null}
{
"error": {
"code": "MISSING_REQUIRED_FIELDS",
"message": "Some required fields are missing.",
"details": {
"missing": ["property.bedrooms", "property.floor"]
}
}
}
```
## Error reference
| HTTP | Code | Message | Details |
| ----- | ------------------------- | ----------------------------------------------- | --------------------------------------- |
| `400` | `INVALID_JSON` | Request body is not valid JSON. | - |
| `401` | `MISSING_TOKEN` | Authorization header is required. | - |
| `401` | `INVALID_TOKEN` | API key is invalid or expired. | - |
| `402` | `INSUFFICIENT_CREDITS` | You don't have enough credits for this request. | `credits_required`, `credits_remaining` |
| `422` | `MISSING_REQUIRED_FIELDS` | Some required fields are missing. | `missing: [...]` |
| `422` | `INVALID_PROPERTY_TYPE` | Invalid property type. | `allowed: [...]` |
| `422` | `INVALID_FIELD_TYPE` | One or more fields have the wrong type. | `fields: [{ field, expected }]` |
| `429` | `RATE_LIMIT_EXCEEDED` | Too many requests. Slow down. | `retry_after` (seconds) |
| `503` | `AI_UNAVAILABLE` | Reasoning service is temporarily unavailable. | - |
| `500` | `INTERNAL_ERROR` | Something went wrong on our end. | - |
## Notes
* `503 AI_UNAVAILABLE` only affects requests with `reasoning: true`. Requests with `reasoning: false` run the scoring engine only and are never affected by AI availability.
* `402 INSUFFICIENT_CREDITS` is returned before any compute runs - your balance is checked first.
* On `429`, respect the `retry_after` value before retrying.
# Create an inquiry
Source: https://docs.majarrah.io/api-reference/inquiries/create
POST https://api.majarrah.io/v1/inquiries
Submit a buyer inquiry against a property listing.
Creates a new inquiry thread between the authenticated user and the property's broker. Requires OAuth or API key authentication.
## Request body
The ID of the property to inquire about.
The buyer's initial message. Plain text, up to 2000 characters.
One of `whatsapp`, `phone`, `email`. Defaults to `whatsapp`.
## Response
Whether a lead credit was charged to the broker's workspace for this inquiry.
## Example
```bash theme={null}
curl https://api.majarrah.io/v1/inquiries \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{
"property_id": "e39a8b2b-...",
"question": "Is the price negotiable? Is there parking?"
}'
```
```json theme={null}
{
"inquiry": {
"id": "a4b1c2d3-...",
"property_id": "e39a8b2b-...",
"status": "open",
"created_at": "2026-09-20T14:30:00Z"
},
"charged": true
}
```
## Errors
See [Error Reference](/api-reference/errors) for shared error codes. Endpoint-specific:
* **`property_not_found`** — the `property_id` doesn't exist or is unpublished.
* **`self_inquiry_forbidden`** — you can't inquire on your own listing.
* **`rate_limited`** — max 10 inquiries per hour per buyer.
# Search Locations
Source: https://docs.majarrah.io/api-reference/locations/search
GET /locations
Look up cities and districts by name. Returns numeric IDs to use in POST /decisions.
## Query parameters
At least one of `city` or `district` is required.
City name to search. Accepts Arabic or English, and handles partial/transliterated input (e.g. `"ryad"` matches `"Riyadh"`). Minimum 2 characters.
When used alone, returns matching city results. When used alongside `district`, scopes the district search to that city.
District or neighbourhood name to search. Accepts Arabic or English. Minimum 2 characters.
When used alone, searches districts across all cities. When used with `city`, scopes results to that city.
Pass `true` alongside `city` to return all districts of that city as a city object. No search is performed — every district is returned.
***
## Response
### Search response (`object: "list"`)
Returned for city and district searches.
Always `"list"` for search responses.
Matching cities and/or districts, max 20 per request.
`"city"` or `"district"`.
Unique numeric ID. Pass as `city_id` or `district_id` in `POST /decisions`.
Official Arabic name.
English transliteration.
Number of districts. Only on `object: "city"` items.
Parent city ID. Only on `object: "district"` items.
Arabic name of the parent city. Only on `object: "district"` items.
English name of the parent city. Only on `object: "district"` items.
Number of items returned.
Only present when `city` was supplied but no city matched. Contains a hint to verify the city name.
### City object response (`object: "city"`)
Returned when `districts=true` is passed alongside `city`.
Always `"city"`.
City numeric ID.
Official Arabic name.
English transliteration.
All districts in this city. Each item has `id`, `name_ar`, `name_en`.
***
## Examples
```bash Search by city name (English) theme={null}
curl "https://api.majarrah.io/v1/locations?city=ryad" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```bash Search by city name (Arabic) theme={null}
curl "https://api.majarrah.io/v1/locations?city=جدة" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```bash Search districts within a city theme={null}
curl "https://api.majarrah.io/v1/locations?district=malqa&city=Riyadh" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```bash Search districts across all cities theme={null}
curl "https://api.majarrah.io/v1/locations?district=corniche" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```bash All districts of a city theme={null}
curl "https://api.majarrah.io/v1/locations?city=Riyadh&districts=true" \
-H "Authorization: Bearer YOUR_API_KEY"
```
```json 200 - City search theme={null}
{
"object": "list",
"data": [
{
"object": "city",
"id": 57834912,
"name_ar": "الرياض",
"name_en": "Riyadh",
"district_count": 312
}
],
"total": 1
}
```
```json 200 - District search (scoped to city) theme={null}
{
"object": "list",
"data": [
{
"object": "district",
"id": 23741856,
"name_ar": "الملقا",
"name_en": "Al Malqa",
"city_id": 57834912,
"city_name_ar": "الرياض",
"city_name_en": "Riyadh"
}
],
"total": 1
}
```
```json 200 - All districts of a city theme={null}
{
"object": "city",
"id": 57834912,
"name_ar": "الرياض",
"name_en": "Riyadh",
"districts": [
{ "id": 23741856, "name_ar": "الملقا", "name_en": "Al Malqa" },
{ "id": 34892710, "name_ar": "النخيل", "name_en": "Al Nakheel" }
]
}
```
```json 200 - City not found theme={null}
{
"object": "list",
"data": [],
"total": 0,
"message": "No city matched 'xyz'. Verify the city name using ?city=xyz."
}
```
```json 400 - Missing params theme={null}
{
"error": "missing_params",
"message": "Provide at least one of: city, district."
}
```
```json 400 - Value too short theme={null}
{
"error": "invalid_param",
"message": "city must be at least 2 characters.",
"field": "city"
}
```
```json 401 - Unauthorized theme={null}
{
"error": "unauthorized",
"message": "Valid Bearer API key required."
}
```
# Search properties
Source: https://docs.majarrah.io/api-reference/properties/search
GET https://api.majarrah.io/v1/properties
Full-text and filter search over Majarrah's published property catalog.
Returns published, moderation-approved listings that match the given filters. Public — no authentication required.
## Query parameters
Free-text query on title, description, city, and district.
City name in Arabic or English. Case-insensitive.
District name in Arabic or English.
Property type slug: `villa`, `apartment`, `commercial-land`, etc. See [Locations](/api-reference/locations/search) for the full list.
Minimum price in SAR (inclusive).
Maximum price in SAR (inclusive).
Minimum bedrooms.
Maximum bedrooms.
Minimum area in square meters.
Maximum area in square meters.
Results per page (1-50).
Starting offset for pagination.
## Response
Array of property objects. Each includes:
Number of results returned (up to `limit`).
Echoed offset for pagination.
## Example
```bash theme={null}
curl "https://api.majarrah.io/v1/properties?city=Riyadh&max_price_sar=1000000&limit=5"
```
```json theme={null}
{
"properties": [
{
"id": "e39a8b2b-...",
"title_en": "3-bedroom villa in Al Yasmin",
"price_sar": 580000,
"area_sqm": 265,
"bedrooms": 3,
"bathrooms": 3,
"city_en": "Riyadh",
"district_en": "Al Yasmin",
"ai_bullets_en": ["Priced below district median", "Warranties included"]
}
],
"count": 1,
"offset": 0
}
```
# API Keys
Source: https://docs.majarrah.io/brokers/api-keys
Server-to-server integration with your Majarrah workspace.
## What API keys are for
An API key lets your own systems talk to Majarrah without a browser session. Common uses:
* Sync inventory from your existing CRM
* Push leads out to HubSpot / Salesforce / Zoho
* Trigger AI decisions programmatically inside your workflows
* Post new listings from a spreadsheet or ERP
You don't need an API key just to use the dashboard or the Claude connector — those use your normal login.
## Create a key
From your sidebar.
Give it a label so you remember where it's used — e.g. `hubspot-sync`, `internal-crm`.
Shown once. Copy it into your secret manager before closing the dialog. It cannot be shown again.
## Use it
Every request includes the key in the `Authorization` header:
```bash theme={null}
curl https://api.majarrah.io/v1/properties/... \
-H "Authorization: Bearer $MAJARRAH_API_KEY"
```
See [API Reference → Authentication](/api-reference/authentication) for the full request format, rate limits, and error shapes.
## Rotate keys regularly
Every key has a **Rotate** action. Rotation issues a new secret and leaves the old one valid for 24 hours, so you can swap without downtime.
Rotate every 90 days as routine hygiene. Give every automation its own key so revoking one doesn't take down the others.
## Revoke immediately if leaked
If a key ever appears in a repo, a log, or a chat message — revoke it now. **Revoke** on the key's row invalidates it in seconds.
Never commit a Majarrah API key to source control. Store keys in your platform's secret manager (Vercel env, AWS Secrets Manager, 1Password, etc.).
## Scopes and permissions
Right now, keys are workspace-scoped and inherit the `owner` role — they can do anything your workspace can. Finer-grained scopes (read-only, listings-only, etc.) are on the roadmap.
# Billing & Credits
Source: https://docs.majarrah.io/brokers/billing
Manage your subscription, inquiry credits, and AI decision packs.
## Overview
Majarrah uses two separate balances:
| Balance | Used for |
| ------------- | ----------------------------------------------------- |
| **Credits** | Responding to buyer inquiries (1 credit per response) |
| **Decisions** | AI decision engine calls (1 or 3 per decision) |
Both are visible at the top of your **Billing** dashboard page.
## Subscription plans
Your subscription plan determines your monthly credit allocation and feature access. Plans renew automatically each month.
You can upgrade, downgrade, or cancel at any time from the Billing page. Changes take effect at the next billing cycle.
## Topping up credits
When your credit balance runs low, buy a credit pack from the Billing page. Packs are one-time purchases that don't expire.
## Decision packs
Decision packs power the AI engine — both for your own use in the dashboard and, when you integrate the API, for your developer calls.
| Pack | Decisions | Best for |
| -------- | --------- | ---------------------------------- |
| Starter | 5 | Occasional use |
| Standard | 20 | Regular use |
| Pro | 50 | High-volume brokers and developers |
All packs include a **24-hour refund guarantee**. If you're not satisfied with the quality of a decision within 24 hours of purchase, contact support for a full refund.
## Usage ledger
Every credit and decision transaction is logged in the billing ledger. The last 20 transactions are shown on the Billing page, with the full history available on request.
## Payment methods
Majarrah supports card payments (Visa, Mastercard, Mada) and Apple Pay. All transactions are processed securely — your card details are never stored on Majarrah's servers.
## Invoices
Invoices are generated automatically for every purchase. Download them from the Billing page.
Only workspace owners and admins can access Billing. Team members with the Agent role cannot see or change billing settings.
# Bookings
Source: https://docs.majarrah.io/brokers/bookings
Manage scheduled property viewings from buyers.
## What are bookings?
When a buyer wants to visit a property, they can request a viewing through the listing page. This creates a booking in your dashboard.
## Viewing bookings
Go to **Bookings** in the sidebar to see all scheduled viewings. Each booking shows:
* The property
* Buyer contact details (phone number)
* Requested date and time
* Current status
## Managing a booking
Click any booking to open it. You can:
* **Confirm** — accept the viewing request
* **Reject** — decline with an optional reason
* **Add notes** — internal notes about the viewing or buyer
## After the viewing
Once a viewing is complete, mark the booking as **Completed**. The buyer receives an automated post-visit survey asking for their feedback on the property and the experience.
## Booking statuses
| Status | Meaning |
| --------- | --------------------------------------- |
| Pending | Buyer requested, awaiting your response |
| Confirmed | Viewing is scheduled |
| Completed | Viewing took place |
| Rejected | You declined the request |
| Cancelled | Buyer cancelled |
# Credits
Source: https://docs.majarrah.io/brokers/credits
How lead credits and AI decision packs work.
## Two separate currencies
Majarrah bills brokers in two independent balances:
Consumed when a buyer reveals your phone number or books a viewing on your listing.
Consumed when you or a buyer request an AI decision on one of your listings.
They're tracked separately so a burst of AI usage doesn't drain your lead runway, and vice versa.
## Where credits come from
* **Your plan's monthly grant**. Every plan (Basic / Growth / Pro / Agency) includes a fixed monthly allocation, refreshed at the start of your billing cycle.
* **Top-up packs**. When you need more mid-cycle, buy packs of 5 / 20 / 50 credits at any time.
* **Trials and promos**. New workspaces get a starter grant. Ghost-broker claimants inherit a 90-day Pro trial.
## Where credits go
Every debit is logged in **Billing → Ledger** with:
* Timestamp
* Reason (phone reveal, viewing booking, AI decision — with pack type)
* Property + buyer involved
* Balance before and after
If something looks wrong, click **Dispute** on the row and it flags the transaction for support review.
## Refunds
Every AI decision pack ships with a 24-hour refund guarantee. If the pack didn't deliver value:
Find the pack purchase.
Explain briefly what didn't work.
Refunds land back on your payment method within 3-5 business days.
Lead credits are not individually refundable, but if you spot an obvious error (a bot reveal, a fake booking), disputing the ledger row triggers a review.
## Balance alerts
Under **Settings → Notifications**, enable low-balance alerts. You'll get an email + push notification when either balance drops below the threshold you set. Never miss a buyer because you ran out mid-day.
Balances don't expire. Unused credits and decisions roll over month-over-month.
# CRM
Source: https://docs.majarrah.io/brokers/crm
Track every lead through a customizable pipeline.
## What Majarrah's CRM is
Every inquiry, viewing request, and phone reveal on your listings creates a **lead** in your CRM. From there, you drag it through a pipeline of stages — `New → Contacted → Qualified → Viewing → Offer → Won / Lost` by default — and keep every note, task, and follow-up in one place.
## Where leads come from
Any buyer who asks a question on one of your listings.
Booked visits become leads automatically.
Every reveal is a lead — even if the buyer never calls, you know they're warm.
Add walk-ins or off-platform leads yourself.
## Pipeline board
Open **CRM** in the sidebar for the kanban board. Drag leads between stages. Each card shows:
* Buyer name (or masked phone if they haven't shared it)
* Which listing they came from
* Days in current stage
* Next scheduled action
Click a card to open its full history — every message, note, task, and viewing.
## Notes and tasks
On any lead:
* **Notes** are free-form text visible to everyone on your team.
* **Tasks** have a due date and an assignee. Overdue tasks trigger notifications.
Both are searchable across the whole CRM.
## Assignment and roles
By default a lead is unassigned. You can:
* Assign it to a specific team member (only they get notifications)
* Leave it in the shared queue (everyone with the `agent` role can grab it)
* Auto-assign new leads via **Settings → CRM Rules** (e.g. round-robin, listing owner takes it)
## Won / Lost outcomes
When a deal closes, mark the lead **Won** and enter the sale price. When it dies, mark **Lost** and pick a reason from the dropdown — reasons feed your monthly analytics so you can see what's killing your pipeline.
Leads never leave your workspace even if a team member does. Removing an ex-employee reassigns their leads back to the shared queue.
# Getting Started
Source: https://docs.majarrah.io/brokers/getting-started
Set up your broker account, create your workspace, and get verified.
## Create your account
Sign up at [www.majarrah.io](https://www.majarrah.io) and select **Broker** as your role during onboarding.
Add your full name, phone number, and agency name.
Your workspace is your agency's hub on Majarrah. Give it a name — this is what your team members and, in some contexts, buyers will see.
Submit your FAL license to unlock full broker features. See [Verification](/brokers/verification) for the full process.
## Your dashboard
After onboarding, you land in the broker dashboard. The sidebar gives you access to:
| Section | What it does |
| ------------ | ------------------------------------------------------ |
| Properties | Add, edit, and manage your listings |
| Inquiries | View and respond to buyer questions |
| Bookings | Manage scheduled property viewings |
| Bulk Import | Upload multiple listings via CSV |
| Verification | Submit and track your FAL/CR verification |
| Billing | Manage your subscription, credits, and decision packs |
| WhatsApp | Connect your WhatsApp number for inquiry notifications |
| AI Agent | Access the AI decision engine |
| Settings | Profile, workspace, and team management |
## Subscription plans
Majarrah offers tiered plans for brokers. Each plan includes a different number of listings, inquiry credits, and AI decisions per month. You can upgrade, downgrade, or cancel from [Billing](/brokers/billing) at any time.
Understand credits, decision packs, and how the pay-per-lead model works.
# Inquiries
Source: https://docs.majarrah.io/brokers/inquiries
Receive and respond to buyer questions on your listings.
## How inquiries work
When a buyer contacts you through a listing, their message appears in your **Inquiries** dashboard. You're notified by email and, if connected, by WhatsApp.
Each inquiry costs one credit from your balance when you respond. Credits are included in your subscription plan and can be topped up via [Billing](/brokers/billing).
## Viewing inquiries
Open **Inquiries** from the sidebar. The badge shows your current open inquiry count.
Each inquiry shows:
* The property it relates to
* The buyer's question
* The date received
* Current status
## Responding
Click an inquiry to open it and write your response. Once sent, the buyer sees your reply in their inquiries page and receives an email notification.
Buyers can follow up with additional questions after your first response. Follow-ups don't consume additional credits.
## Lead outcomes
After responding, you can mark the lead outcome to track your conversion:
| Outcome | When to use |
| ---------------- | ---------------------------- |
| Bought | Buyer purchased the property |
| Still Interested | Ongoing conversation |
| Not Interested | Buyer moved on |
Tracking outcomes helps you measure your lead conversion rate over time.
## Inquiry status
| Status | Meaning |
| ------- | --------------------------------- |
| Open | New inquiry, not yet responded to |
| Replied | You've sent a response |
| Closed | Resolved or expired |
## Credit tracking
Each inquiry response is logged in your billing ledger. You can see all credit usage in the [Billing](/brokers/billing) page under the credit history section.
# Managing Listings
Source: https://docs.majarrah.io/brokers/listings
Add, edit, and manage your property listings on Majarrah.
## Adding a listing
From the dashboard, go to **Properties** and click **Add Property**.
Fill in the required details:
* **Title** (Arabic and English)
* **Type** - Apartment, Villa, Land, Shop, Office
* **Price**
* **Location** - City and district
* **Area** (sqm)
* **Bedrooms and bathrooms** (where applicable)
* **Description** (Arabic and English)
* **Images** - Upload at least one photo
Once submitted, your listing goes to the Majarrah moderation queue. It's published after approval, typically within 1 business day.
## Bulk import
If you have multiple listings, use **Bulk Import** in the sidebar to upload them all at once via a CSV or Excel file.
The import tool validates each row and reports errors per listing, so you can fix issues without re-uploading everything.
The template includes all required and optional columns with formatting guidelines.
## Editing a listing
Go to **Properties**, find the listing, and click **Edit**. All fields are editable after publishing. Changes go live immediately — no re-moderation required for edits.
## Featured listings
You can mark a listing as **Featured** from the Properties table. Featured listings appear at the top of search results and browse pages.
Featured status is subject to your plan's featured listing quota.
## Deleting a listing
Click the listing in your Properties table and select **Delete**. This permanently removes the listing and all associated data (images, view counts). Buyer inquiries linked to the listing are archived.
Deletion is permanent. Active buyer inquiries on the listing will be closed.
## Listing status
| Status | Meaning |
| --------- | ----------------------------------- |
| Pending | Under moderation review |
| Published | Live and visible to buyers |
| Rejected | Rejected by moderation — see reason |
| Draft | Saved but not submitted |
# Public Broker Page
Source: https://docs.majarrah.io/brokers/public-page
Your agency's public profile on Majarrah — bio, active listings, WhatsApp CTA.
## What the public page is
Every broker workspace on Majarrah gets a **public page** at:
```
https://www.majarrah.io/broker/
```
It's your public face on the marketplace: bio, verified badge, current listings, viewing hours, WhatsApp CTA. Buyers can browse everything you've published without an account.
## Set it up
From your dashboard sidebar.
Short and memorable. Once set, it lives in the URL — changing it later breaks any inbound links.
A short pitch in both Arabic and English. Think 2-3 sentences: who you are, what areas you cover, what makes you different.
Square, transparent background, at least 256×256px.
Toggle the **Published** switch. Your page goes live immediately.
## What buyers see
Front and center.
FAL Verified and CR Verified badges appear if you've completed those verifications.
All published + moderated listings, most recent first.
Big WhatsApp button that pre-fills a first message. Only shown if you've connected WhatsApp.
## Track visits
Under **Settings → Public page → Analytics** you'll see:
* Total page views
* WhatsApp CTA clicks (a key intent signal)
* Traffic sources (where the visits came from)
The WhatsApp click count is also broken down per source so you can see if a listing on Snapchat is actually driving conversations.
## Share it
Once published, share your handle everywhere: your bio on Snapchat, Instagram, X, WhatsApp, business cards. The page is designed to convert: whether the visitor knows Majarrah or not, they can browse and message you in seconds.
Your public page only shows listings that are both **Published** and **Moderation-approved**. Pending or rejected listings are hidden.
# Team & Workspace
Source: https://docs.majarrah.io/brokers/team
Invite team members, manage roles, and configure your workspace.
## Workspace
Your workspace is your agency's account on Majarrah. It holds your listings, team, billing, and settings under one roof.
### Workspace settings
Go to **Settings - Workspace** to update:
* Workspace name
* Workspace slug (used in your public URLs)
Only workspace owners and admins can edit workspace settings.
### Deleting a workspace
The **Danger Zone** at the bottom of Workspace settings lets you permanently delete your workspace. This removes all listings, team members, billing history, and data. This action cannot be undone.
Deleting your workspace is permanent and immediate. All active listings will be unpublished.
## Team members
Go to **Settings - Team** to manage your team.
### Roles
| Role | What they can do |
| ----- | --------------------------------------------------------------------- |
| Owner | Full access — billing, settings, team, all features |
| Admin | Same as owner except cannot delete the workspace |
| Agent | Listings, inquiries, bookings — no access to billing or team settings |
### Inviting someone
Click **Invite Member**, enter their email address, and select a role. They receive an invitation email with a link to join your workspace.
If they don't have a Majarrah account, they'll be prompted to create one first.
### Removing a member
Click the member's row in the team list and select **Remove**. They lose access to your workspace immediately. Their account is not deleted — they can still log in with a personal account.
## Profile settings
Go to **Settings - Profile** to update your:
* Display name
* Email address
* Phone number
* Profile photo
# Verification
Source: https://docs.majarrah.io/brokers/verification
Get your FAL or CR verified to unlock full broker features.
## Why verify?
Verified brokers get a **FAL verified badge** displayed on their listings and profile. This increases buyer trust and is required to fully activate your account on Majarrah.
## FAL verification (individuals)
FAL is the real estate broker license issued by the Saudi Real Estate General Authority.
Open the **Verification** page from your dashboard sidebar.
Upload a clear image or PDF of your FAL license. Make sure the license number, name, and expiry date are visible.
The Majarrah team reviews submissions within 1 business day.
Once approved, your listings show the FAL verified badge and your account is fully activated.
## CR verification (institutions)
For real estate companies and institutions, submit your Commercial Register (CR) document instead of a FAL license.
The process is identical — go to **Verification**, select CR, and upload your document.
## Verification statuses
| Status | Meaning |
| ---------- | -------------------------------------- |
| Unverified | No submission yet |
| Pending | Submitted, under review |
| Approved | Verified — badge active |
| Rejected | Submission rejected — see reason below |
## If rejected
The rejection reason is displayed on the Verification page. Common reasons:
* Document is expired
* Image is unclear or cropped
* Name on document doesn't match account name
Fix the issue and resubmit. There's no limit on resubmissions.
Submitting fraudulent documents results in permanent account suspension.
# WhatsApp Integration
Source: https://docs.majarrah.io/brokers/whatsapp
Receive buyer inquiry notifications directly on WhatsApp.
## What it does
Connect your WhatsApp number to receive a notification every time a buyer sends an inquiry on one of your listings. You still respond through the Majarrah dashboard — this is a notification channel, not a chat replacement.
## Setup
Open **WhatsApp** from your dashboard sidebar.
Select your country code and enter your WhatsApp number.
You'll receive a verification code on WhatsApp. Enter it to confirm.
Toggle notifications on. New inquiry alerts will be sent to your WhatsApp immediately.
## Changing your number
To update your WhatsApp number, go back to the WhatsApp page, disable the current number, and set up a new one.
## Disabling notifications
Toggle the notifications switch off on the WhatsApp page at any time. Your number stays saved so you can re-enable without re-verifying.
# AI Agent
Source: https://docs.majarrah.io/buyers/ai-agent
Have a conversation with Majarrah's AI to find and evaluate properties.
## What is the AI Agent?
The AI Agent is a conversational interface that reasons about real estate on your behalf. Instead of filtering listings manually, you describe what you're looking for and the agent finds and evaluates properties for you.
You can ask it things like:
* "Find me a 3-bedroom apartment in Riyadh under SAR 800,000"
* "Is this villa in Al Nakheel a good investment at this price?"
* "Compare these two properties for me"
* "What are prices like in Dubai Marina right now?"
## Starting a session
Go to the AI Agent from your dashboard sidebar. Each conversation is a session — you can start a new one at any time, and your previous sessions are saved.
You can also open the agent directly on a specific property by clicking **Ask AI** from any listing page. The agent opens pre-loaded with that property's context.
## How it works
Type your query in Arabic or English. The agent understands both.
The engine pulls relevant property data and market benchmarks, then reasons through your query.
You receive a verdict, score breakdown, and an explanation — not just a list of links.
Ask follow-up questions. The agent keeps context across the conversation.
## Decision credits
Each AI response that produces a property verdict consumes decisions from your balance. Scoring-only responses cost 1 decision; responses with full reasoning cost 3.
Packs start at 5 decisions. All come with a 24-hour refund guarantee.
## Tips
* Be specific about location, budget, and purpose (own use vs. investment) — the more context you give, the sharper the verdict
* You can paste a property URL directly into the chat to get an instant analysis
* Switch languages mid-conversation — the agent follows your lead
# AI Reports
Source: https://docs.majarrah.io/buyers/ai-reports
Deep-dive AI analysis on a listing, a neighborhood, or your whole shortlist.
## What an AI report is
An **AI report** is a longer, structured deliverable from Majarrah's decision engine. Where a single AI decision gives you a verdict on one listing, a report can:
* Compare multiple listings side-by-side
* Analyze a neighborhood's price trajectory
* Score your whole saved shortlist against your goals
* Draft a negotiation strategy for a specific listing
Reports are exportable — save as PDF, share a link, forward to your advisor or family.
## Report types
Full breakdown of one property: price vs. market, red flags, negotiation levers.
Pit your saved listings against each other and see which one wins on your criteria.
7-year price trajectory, appreciation %, bubble signal for a given city + district.
Break-even analysis for a listing at current mortgage rates.
## How to generate one
Buyer sidebar → **Reports** → **New report**.
Each type asks a few structured questions — budget, goals, timeframe.
A listing, a shortlist, or a neighborhood.
The engine runs the analysis in the background. When it's ready, you get a notification.
## Cost
Reports consume AI queries from your account balance. See [Decisions](/decisions) for the cost of each report type. Every account starts with a small pack of free queries — no credit card required.
## Share a report
Every report has a **Share** button. Options:
* **Copy public link**: a read-only URL anyone with the link can open (no login).
* **Export PDF**: fully formatted document with your logo (if set).
* **Email**: send to one or more addresses; recipient sees the report immediately.
Public links can be revoked at any time from **Reports → Manage links**. Once revoked, previously copied links stop working.
# Inquiries
Source: https://docs.majarrah.io/buyers/inquiries
Send questions to brokers and track their responses.
## Sending an inquiry
From any property page, click **Contact Broker** to send a question. Your message goes directly to the broker managing that listing.
Keep your inquiry specific — brokers respond faster to clear questions about availability, price negotiation, or viewing requests.
## Tracking responses
Go to [Inquiries](https://www.majarrah.io/inquiries) from your account to see all your sent inquiries and broker responses.
Each inquiry shows:
* The property it relates to
* Your original question
* The broker's response (when replied)
* The response date
* Current status
## Booking a viewing
Once a broker responds, you can coordinate a property viewing directly. After the viewing, Majarrah sends you a short survey to collect your feedback.
## Inquiry status
| Status | Meaning |
| ------- | ------------------------------ |
| Pending | Sent, waiting for broker reply |
| Replied | Broker has responded |
| Closed | Inquiry resolved or expired |
Brokers are notified of new inquiries via email and WhatsApp (if they've connected their number). Most respond within 24 hours.
# Reveal Broker Phone
Source: https://docs.majarrah.io/buyers/reveal-phone
How phone reveals work and what they cost.
## Why we hide phone numbers by default
Broker phone numbers are hidden on listing pages until you explicitly reveal them. Two reasons:
1. **Privacy for brokers**: they don't get spammed by scrapers or bots.
2. **Higher intent from you**: revealing a number is a small commitment that filters out casual clicks.
Everything else on a listing — full specs, images, description, AI verdict — is visible without revealing anything.
## The reveal flow
On any listing page, next to the broker's name.
You'll see a small dialog reminding you the reveal is logged and the broker will know you're interested.
The full phone number appears, along with a WhatsApp shortcut and a copy button.
## Cost
**For buyers**: **free**. You don't pay for reveals.
**For brokers**: workspaces on a paid plan are charged one **lead credit** per reveal. Free-plan workspaces are limited to a small number of reveals per month. See [Broker Billing](/brokers/billing) for details.
## Reveal history
Every reveal you make is logged under **Profile → Reveal history**. You can see:
* Which broker you called
* Which listing you were looking at
* When you revealed
Handy when you can't remember which broker had the villa you called about last week.
## Safety
Never send money to a broker before viewing the property in person and verifying their FAL license. Majarrah's FAL Verified badge is a strong signal, but a physical visit is the final check. See our [safety tips](https://www.majarrah.io/safety) for more.
# Saved Properties
Source: https://docs.majarrah.io/buyers/saved
Bookmark properties and revisit them anytime.
## Saving a property
Click the heart icon on any listing — from the browse page or the property detail page — to save it. You need a free account to save properties.
## Viewing your saved list
Go to [Likes](https://www.majarrah.io/likes) from your account. All saved properties appear here with their current price and key details.
## Removing a property
Click the heart icon again on any saved property to unsave it. The property is removed from your list immediately.
If a listing is removed by the broker or taken off the market, it disappears from your saved list automatically.
# Searching Properties
Source: https://docs.majarrah.io/buyers/search
Browse and filter properties across Saudi Arabia and the UAE.
## Browse listings
Go to the [Properties](https://www.majarrah.io/properties) page to browse all published listings. Each card shows the property image, price, location, and key specs (bedrooms, bathrooms, area).
## Filters
Use the search bar and filters to narrow down results by:
* Location (city, district, neighborhood)
* Property type (apartment, villa, land, commercial)
* Price range
* Number of bedrooms
* Area (sqm)
## Property detail page
Click any listing to open the full property page. Here you'll find:
* Full image gallery
* Complete specs and description (Arabic and English)
* Broker contact information and verification badge
* View count
* Safety tips for dealing with brokers
## Save a property
Click the heart icon on any listing to save it to your favorites. Access all saved properties from the [Likes](/buyers/saved) page.
Saving a property requires a free account. Sign up at [www.majarrah.io](https://www.majarrah.io).
## Get an AI decision
From any property page, you can request an AI decision — a structured verdict on whether the property is a good fit for your criteria.
Understand how the engine scores properties and what each decision costs.
# Viewings
Source: https://docs.majarrah.io/buyers/viewings
Book a property viewing, prepare for it, and share feedback after.
## Book a viewing
From any listing's page, click **Book viewing**. You'll see the broker's available time slots — days of the week they accept viewings and the times within each day.
Only available slots are clickable. Slots grey out once fully booked.
Your phone number is pre-filled from your profile. The broker uses it to confirm and coordinate on the day.
You'll receive a confirmation immediately in-app; the broker gets notified via email + WhatsApp.
## Before you go
Saudi brokers are required to verify visitor identity before entering a property.
The exact address is on the listing detail page. Screenshot it for offline access.
Delivery date, HOA fees, neighborhood noise, sun orientation — jot these down before you go so you don't forget on-site.
Before or after the viewing, request a decision on the listing to double-check your gut.
## My viewings
Open **My viewings** in the sidebar to see everything you've booked. Sorted by date, next visit at the top. Each row shows status:
* **Pending**: awaiting broker confirmation.
* **Confirmed**: broker has approved. Add it to your calendar with one click.
* **Cancelled**: either party cancelled. Reason is on the row.
* **Completed**: the visit happened. You'll be invited to share feedback.
## Cancel or reschedule
Click the row and use **Cancel** or **Reschedule**. Rescheduling opens the same time picker as booking. Cancelling ≤ 4 hours before the slot is treated as a no-show and may temporarily restrict future viewings if repeated.
## Post-viewing survey
Every completed viewing triggers a short survey (three questions, one minute). Your feedback:
* Helps Majarrah surface brokers who deliver a great experience
* Feeds the AI decision engine's confidence in a listing
* Is anonymous to the broker unless you opt-in to share your name
Missed a viewing without cancelling? Please still leave feedback — even "didn't show up" is useful signal for us.
# AI Decisions
Source: https://docs.majarrah.io/decisions
How Majarrah's decision engine works and what decisions cost.
## What is a decision?
A decision is a structured verdict on a property. Instead of just showing you a listing, Majarrah reasons about it — comparing price against market benchmarks, scoring the location, evaluating the specs, and returning a clear verdict.
Every decision returns:
* A **verdict** - `match`, `partial`, or `no_match`
* A **score** from 0 to 100
* A **breakdown** across price, location, size, and property-specific details
* Optionally, a **reasoning** paragraph in Arabic or English
## Two modes
Pure algorithmic comparison against market data. Returns the score and breakdown instantly. Costs **1 decision**.
Scoring + AI explanation. Adds a plain-language paragraph explaining the verdict. Costs **3 decisions**.
## Decision packs
Decisions are purchased in packs. All packs include a **24-hour refund guarantee**.
| Pack | Decisions | Best for |
| -------- | --------- | ---------------------- |
| Starter | 5 | Evaluating a shortlist |
| Standard | 20 | Active property search |
| Pro | 50 | Brokers and investors |
You can buy packs from your [billing page](/brokers/billing) inside the dashboard.
## How scoring works
The engine scores every property across four weighted buckets:
| Bucket | Weight | What it measures |
| -------- | ------ | ------------------------------------------------------------------ |
| Price | 30% | Property price vs. market average for the location, type, and size |
| Location | 20% | Area demand, market trend, proximity to preferences |
| Size | 20% | Price per sqm vs. market benchmark |
| Details | 30% | Type-specific factors: bedrooms, floor, elevator, zoning, etc. |
Each bucket returns a score from 0–100 and a status (`pass`, `warn`, or `fail`). The weighted average becomes the final score.
**Verdict thresholds:**
* 70–100 → `match`
* 40–69 → `partial`
* 0–39 → `no_match`
## Confidence
The confidence level (`high`, `medium`, or `low`) reflects how much data was available to make the decision. Providing more property details raises confidence.
Decisions never go stale — if you want a fresh verdict on the same property, simply request a new one. Market benchmarks update continuously.
# API Keys
Source: https://docs.majarrah.io/developers/api-keys
Generate keys for server-to-server integration with your Majarrah workspace.
## When you need an API key
An API key lets your own systems talk to Majarrah without a browser session — sync inventory from your CRM, push new projects from your ERP, mirror leads into HubSpot / Salesforce.
You don't need a key for:
* Rendering the widget (the widget uses a public `data-developer` slug)
* Team members logging into the dashboard (they use their own account)
You **do** need one for:
* Programmatic listing creates/updates
* Pulling leads out into your own CRM
* Custom AI Decision integrations
* Any server-side automation
## Create a key
From your dashboard sidebar.
Give it a label (e.g. `crm-sync-prod`) so you know where it's used.
The secret is shown once. Store it in your secret manager immediately. You cannot recover it later.
## Use it
Every API request includes the key in the `Authorization` header:
```bash theme={null}
curl https://api.majarrah.io/v1/... \
-H "Authorization: Bearer $MAJARRAH_API_KEY"
```
See [API Reference → Authentication](/api-reference/authentication) for full details on request signing, rate limits, and errors.
## Rotate or revoke
Every key on your list has a **Rotate** and **Revoke** action:
* **Rotate** issues a fresh secret and gives you a 24-hour grace window where both old and new work. Use it to swap keys without downtime.
* **Revoke** invalidates the key immediately. Use it if you suspect a secret was leaked.
## Key hygiene
Never commit an API key to source control. Never share one over email or chat. If a key was ever exposed publicly — even briefly — revoke and rotate it immediately.
Rotate keys every 90 days as a matter of routine. Give every automation its own key so revoking one doesn't take down others.
# Getting Started
Source: https://docs.majarrah.io/developers/getting-started
Set up your developer account and launch your project's AI assistant.
## Who this is for
The **Developer** persona is for real-estate developers who own projects — off-plan compounds, phased releases, master-planned communities. You get a dedicated subdomain, an embeddable AI widget for your website, and a lead inbox that consolidates every question a buyer asks about your projects.
## Create your account
You'll receive an invite from Majarrah at the email you registered with. The invite link takes you straight into onboarding — no separate sign-up.
Click the link in the invite email. You'll create your password on first login.
Verify your legal entity name (Arabic + English), your official logo, and your website. This is what appears on your public developer page.
Pick a slug — e.g. `roshn` becomes `roshn.majarrah.io`. This is where your team logs in and where the widget script points.
## Your dashboard
Once inside, you land on your developer dashboard at `.majarrah.io/dashboard`. The sidebar gives you:
| Section | What it does |
| ---------- | ---------------------------------------------------- |
| Overview | Widget stats, unread messages, new leads at a glance |
| Projects | Your master list of projects and their properties |
| Properties | Every unit across every project |
| Inquiries | Buyer questions raised on your listings |
| Leads | New leads captured by the widget, ready to hand off |
| CRM | Stage-based pipeline for every lead |
| Visits | Scheduled viewings across all your projects |
| Inbox | The widget's real-time visitor chat threads |
| AI Agent | Configure and test your on-site assistant |
| Settings | Team, billing, API keys, WhatsApp, widget config |
## What's next
Group units by phase, tower, or community.
A single script tag turns your site into a lead-capturing assistant.
Answer buyer questions accurately with your own docs.
Add sales reps and account managers to your workspace.
# Projects
Source: https://docs.majarrah.io/developers/projects
Group your properties by development, phase, or master community.
## What is a project?
A **project** is a container for related properties — a single tower, a compound release, or a full master-planned community. Every property in your workspace belongs to exactly one project. Widget answers, AI verdicts, and reporting all roll up per-project.
## Create a project
From the sidebar, open **Projects → New project**.
Give the project a display name (Arabic + English) and a short slug. The slug shows up in URLs and in the AI's replies to buyers.
Pick the city and district using Majarrah's location picker. The city/district feed price benchmarks and market comparisons in the AI answers.
Add a hero image and a short marketing blurb. This is what buyers see when the widget references the project.
Add expected handover date, payment plan summary, and off-plan status. The AI cites these when buyers ask about timing or terms.
## Add properties to a project
Every property you add via **Properties → New listing** is attached to one project. If you have multiple projects, pick from the dropdown at the top of the form. Unit specs (bedrooms, bathrooms, area) are per-property; project-level info (payment plan, delivery date) is inherited.
## Project analytics
Open a project to see:
* Unit availability status
* Views by property
* Inquiries per unit
* New leads captured for this project
* Widget messages mentioning this project by name
## Public project page
Every project has a public URL: `.majarrah.io/projects/`. Buyers can browse, filter units, and start a conversation with the widget from this page.
Projects are not visible on the public Majarrah marketplace until at least one property inside them is published and moderation-approved.
# Team
Source: https://docs.majarrah.io/developers/team
Invite sales reps, account managers, and admins to your developer workspace.
## Roles
Your developer workspace has three role tiers:
| Role | Can do |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Owner** | Everything, including billing, deleting the workspace, and reassigning ownership. There's exactly one owner. |
| **Admin** | Everything except billing and ownership transfer. Best for country managers, ops leads. |
| **Agent** | Access properties, inquiries, leads, and inbox. Cannot manage team, API keys, or the widget config. Best for individual sales reps. |
## Invite someone
From your dashboard sidebar.
Enter their email and pick a role.
They receive an email with a magic link. On first login they set their password and land straight in your workspace.
## Change a role
Every team member row has a role dropdown. Promoting an agent to admin, or demoting an admin to agent, takes effect on their next page load. Owners cannot be demoted — instead, transfer ownership first (see below).
## Remove someone
Click **Remove** next to their name. They lose all access immediately, but any leads they've been assigned stay with your workspace — they don't leave with them.
## Transfer ownership
Only the current owner can do this. Under **Settings → Team → Ownership**, pick an existing admin and confirm. The old owner is downgraded to admin. There's no undo without the new owner's consent.
If a team member leaves your organization, remove them from Majarrah on the same day. Ex-employees with active accounts can still see live pipeline data.
## Accounts across developers
A person can be a member of multiple developer workspaces on Majarrah — useful for external agencies representing several developers. On login they pick which workspace to enter.
# The Widget
Source: https://docs.majarrah.io/developers/widget
Embed Majarrah's AI assistant on your own website in one line.
## What the widget does
The Majarrah **widget** is an on-site AI chat that answers buyer questions about your projects in real time — pricing, availability, floor plans, payment terms, delivery dates, brochure links. Every conversation is captured as a lead in your inbox, so nothing slips through.
It's trained on:
* Your project + unit data on Majarrah
* Your uploaded knowledge base (brochures, FAQs, policies — see [Knowledge Base](/developers/widget-knowledge-base))
* Live market data (city/district benchmarks) so the AI can contextualize price
* Nothing else — the widget never leaks another developer's information
## Install it
Go to **Settings → Widget** in your dashboard. Copy the script tag and paste it before the closing `` of every page you want the widget on.
```html theme={null}