Create a Decision
curl --request POST \
--url https://api.majarrah.io/v1/decisions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"property": {
"type": "<string>",
"price": 123,
"area": 123,
"bedrooms": 123,
"bathrooms": 123,
"floor": 123,
"age": 123,
"parking": true,
"furnished": true
},
"location": {
"city": "<string>",
"district": "<string>",
"lat": 123,
"lng": 123
},
"reasoning": true
}
'import requests
url = "https://api.majarrah.io/v1/decisions"
payload = {
"property": {
"type": "<string>",
"price": 123,
"area": 123,
"bedrooms": 123,
"bathrooms": 123,
"floor": 123,
"age": 123,
"parking": True,
"furnished": True
},
"location": {
"city": "<string>",
"district": "<string>",
"lat": 123,
"lng": 123
},
"reasoning": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
property: {
type: '<string>',
price: 123,
area: 123,
bedrooms: 123,
bathrooms: 123,
floor: 123,
age: 123,
parking: true,
furnished: true
},
location: {city: '<string>', district: '<string>', lat: 123, lng: 123},
reasoning: true
})
};
fetch('https://api.majarrah.io/v1/decisions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.majarrah.io/v1/decisions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'property' => [
'type' => '<string>',
'price' => 123,
'area' => 123,
'bedrooms' => 123,
'bathrooms' => 123,
'floor' => 123,
'age' => 123,
'parking' => true,
'furnished' => true
],
'location' => [
'city' => '<string>',
'district' => '<string>',
'lat' => 123,
'lng' => 123
],
'reasoning' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.majarrah.io/v1/decisions"
payload := strings.NewReader("{\n \"property\": {\n \"type\": \"<string>\",\n \"price\": 123,\n \"area\": 123,\n \"bedrooms\": 123,\n \"bathrooms\": 123,\n \"floor\": 123,\n \"age\": 123,\n \"parking\": true,\n \"furnished\": true\n },\n \"location\": {\n \"city\": \"<string>\",\n \"district\": \"<string>\",\n \"lat\": 123,\n \"lng\": 123\n },\n \"reasoning\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.majarrah.io/v1/decisions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"property\": {\n \"type\": \"<string>\",\n \"price\": 123,\n \"area\": 123,\n \"bedrooms\": 123,\n \"bathrooms\": 123,\n \"floor\": 123,\n \"age\": 123,\n \"parking\": true,\n \"furnished\": true\n },\n \"location\": {\n \"city\": \"<string>\",\n \"district\": \"<string>\",\n \"lat\": 123,\n \"lng\": 123\n },\n \"reasoning\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.majarrah.io/v1/decisions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"property\": {\n \"type\": \"<string>\",\n \"price\": 123,\n \"area\": 123,\n \"bedrooms\": 123,\n \"bathrooms\": 123,\n \"floor\": 123,\n \"age\": 123,\n \"parking\": true,\n \"furnished\": true\n },\n \"location\": {\n \"city\": \"<string>\",\n \"district\": \"<string>\",\n \"lat\": 123,\n \"lng\": 123\n },\n \"reasoning\": true\n}"
response = http.request(request)
puts response.read_body{
"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
},
"decisions_used": 1,
"decisions_remaining": 99
}
{
"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"]
},
"decisions_used": 3,
"decisions_remaining": 97
}
{
"error": "invalid_api_key",
"message": "Provide a valid Bearer token. API keys start with sk- and can be created in your dashboard."
}
{
"error": "insufficient_decisions",
"message": "This request requires 3 decisions. Your workspace has 1. Purchase more at www.majarrah.io.",
"required": 3,
"balance": 1
}
{
"error": "validation_error",
"message": "property.area must be a positive number (sqm).",
"field": "property.area"
}
Decisions
Create a Decision
Evaluate a property and get a structured verdict.
POST
/
decisions
Create a Decision
curl --request POST \
--url https://api.majarrah.io/v1/decisions \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"property": {
"type": "<string>",
"price": 123,
"area": 123,
"bedrooms": 123,
"bathrooms": 123,
"floor": 123,
"age": 123,
"parking": true,
"furnished": true
},
"location": {
"city": "<string>",
"district": "<string>",
"lat": 123,
"lng": 123
},
"reasoning": true
}
'import requests
url = "https://api.majarrah.io/v1/decisions"
payload = {
"property": {
"type": "<string>",
"price": 123,
"area": 123,
"bedrooms": 123,
"bathrooms": 123,
"floor": 123,
"age": 123,
"parking": True,
"furnished": True
},
"location": {
"city": "<string>",
"district": "<string>",
"lat": 123,
"lng": 123
},
"reasoning": True
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
property: {
type: '<string>',
price: 123,
area: 123,
bedrooms: 123,
bathrooms: 123,
floor: 123,
age: 123,
parking: true,
furnished: true
},
location: {city: '<string>', district: '<string>', lat: 123, lng: 123},
reasoning: true
})
};
fetch('https://api.majarrah.io/v1/decisions', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.majarrah.io/v1/decisions",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'property' => [
'type' => '<string>',
'price' => 123,
'area' => 123,
'bedrooms' => 123,
'bathrooms' => 123,
'floor' => 123,
'age' => 123,
'parking' => true,
'furnished' => true
],
'location' => [
'city' => '<string>',
'district' => '<string>',
'lat' => 123,
'lng' => 123
],
'reasoning' => true
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.majarrah.io/v1/decisions"
payload := strings.NewReader("{\n \"property\": {\n \"type\": \"<string>\",\n \"price\": 123,\n \"area\": 123,\n \"bedrooms\": 123,\n \"bathrooms\": 123,\n \"floor\": 123,\n \"age\": 123,\n \"parking\": true,\n \"furnished\": true\n },\n \"location\": {\n \"city\": \"<string>\",\n \"district\": \"<string>\",\n \"lat\": 123,\n \"lng\": 123\n },\n \"reasoning\": true\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.majarrah.io/v1/decisions")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"property\": {\n \"type\": \"<string>\",\n \"price\": 123,\n \"area\": 123,\n \"bedrooms\": 123,\n \"bathrooms\": 123,\n \"floor\": 123,\n \"age\": 123,\n \"parking\": true,\n \"furnished\": true\n },\n \"location\": {\n \"city\": \"<string>\",\n \"district\": \"<string>\",\n \"lat\": 123,\n \"lng\": 123\n },\n \"reasoning\": true\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.majarrah.io/v1/decisions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"property\": {\n \"type\": \"<string>\",\n \"price\": 123,\n \"area\": 123,\n \"bedrooms\": 123,\n \"bathrooms\": 123,\n \"floor\": 123,\n \"age\": 123,\n \"parking\": true,\n \"furnished\": true\n },\n \"location\": {\n \"city\": \"<string>\",\n \"district\": \"<string>\",\n \"lat\": 123,\n \"lng\": 123\n },\n \"reasoning\": true\n}"
response = http.request(request)
puts response.read_body{
"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
},
"decisions_used": 1,
"decisions_remaining": 99
}
{
"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"]
},
"decisions_used": 3,
"decisions_remaining": 97
}
{
"error": "invalid_api_key",
"message": "Provide a valid Bearer token. API keys start with sk- and can be created in your dashboard."
}
{
"error": "insufficient_decisions",
"message": "This request requires 3 decisions. Your workspace has 1. Purchase more at www.majarrah.io.",
"required": 3,
"balance": 1
}
{
"error": "validation_error",
"message": "property.area must be a positive number (sqm).",
"field": "property.area"
}
Request body
object
required
The property to evaluate.
Show property fields
Show property fields
string
required
Property type. One of:
apartment, villa, land, commercial, officenumber
required
Asking price in SAR.
number
required
Total area in square meters.
number
Number of bedrooms.
number
Number of bathrooms.
number
Floor number. Use
0 for ground floor.number
Property age in years.
boolean
Whether parking is available.
boolean
Whether the property is furnished.
object
required
boolean
required
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
string
match, partial, or no_match. Derived from score: 70+ is match, 40–69 is partial, below 40 is no match.number
Overall score from 0 to 100.
object
Per-bucket scores and statuses.
Show breakdown fields
Show breakdown fields
object
score (0–100) and status (pass, warn, fail). Compares property price against market benchmarks.object
score and status. Area demand and market trend.object
score and status. Price per sqm vs. market average for the type and location.object
score and status. Type-specific factors: bedrooms, floor, age, parking, etc.number
Calculated price per square meter for this property.
object | null
MOJ market data used for price scoring.
null if no benchmark exists for the given city/district.Show benchmark fields
Show benchmark fields
number
Median transaction price per sqm (SAR) for this city/district. The midpoint — half of transactions were above, half below.
number
25th percentile price per sqm. Properties priced at or below this are considered well-priced.
number
75th percentile price per sqm. Properties priced above this are considered expensive for the area.
number
Year of the benchmark data (MOJ transaction year).
number
Number of transactions used to compute the benchmark.
number | null
Year-over-year price change percentage vs. the prior year.
null if no prior-year data is available.object
number
Decisions consumed by this request.
1 for scoring only, 3 for reasoning.number
Your remaining decision balance after this request.
Examples
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
}'
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
}'
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
}'
{
"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
},
"decisions_used": 1,
"decisions_remaining": 99
}
{
"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"]
},
"decisions_used": 3,
"decisions_remaining": 97
}
{
"error": "invalid_api_key",
"message": "Provide a valid Bearer token. API keys start with sk- and can be created in your dashboard."
}
{
"error": "insufficient_decisions",
"message": "This request requires 3 decisions. Your workspace has 1. Purchase more at www.majarrah.io.",
"required": 3,
"balance": 1
}
{
"error": "validation_error",
"message": "property.area must be a positive number (sqm).",
"field": "property.area"
}
Was this page helpful?