Overview
Base URL: https://api.tarin.keys.krd. All requests use HTTPS and a partner key.
| Method | Path | Purpose |
|---|---|---|
| GET | /v1/units | All villas with status, areas, rooms and (optionally) prices. JSON or CSV. |
| POST | /v1/enquiries | Create an enquiry for the Tarin Hills sales team. |
Responses are read live from the sales system and are not cached. The feed contains no personal or deal data.
Create a key
You generate the key. Send us only its prefix and its SHA-256 hash; the key itself never leaves your systems.
- Generate a key:
thk_followed by 48 lowercase hexadecimal characters (24 random bytes). - Store the key in your secret manager. It cannot be recovered from what you send us.
- Send your Tarin Hills contact the prefix (the first 12 characters, e.g.
thk_1a2b3c4d) and the hash (64 hexadecimal characters). Neither is secret. - Wait for confirmation that the key is registered. Requests with an unregistered key return
401.
KEY="thk_$(openssl rand -hex 24)"
echo "Key (keep secret): $KEY"
echo "Prefix: ${KEY:0:12}"
echo "SHA-256: $(printf %s "$KEY" | shasum -a 256 | cut -d' ' -f1)"
$bytes = New-Object byte[] 24
[Security.Cryptography.RandomNumberGenerator]::Create().GetBytes($bytes)
$key = 'thk_' + (($bytes | ForEach-Object { $_.ToString('x2') }) -join '')
$sha = [Security.Cryptography.SHA256]::Create().ComputeHash([Text.Encoding]::UTF8.GetBytes($key))
"Key (keep secret): $key"
"Prefix: $($key.Substring(0, 12))"
"SHA-256: $(($sha | ForEach-Object { $_.ToString('x2') }) -join '')"
const crypto = require('node:crypto');
const key = 'thk_' + crypto.randomBytes(24).toString('hex');
console.log('Key (keep secret):', key);
console.log('Prefix:', key.slice(0, 12));
console.log('SHA-256:', crypto.createHash('sha256').update(key).digest('hex'));
import hashlib, secrets
key = "thk_" + secrets.token_hex(24)
print("Key (keep secret):", key)
print("Prefix:", key[:12])
print("SHA-256:", hashlib.sha256(key.encode()).hexdigest())
To rotate, generate a new key and send its prefix and hash; switch once it is registered, then ask us to revoke the old one. A revoked key returns 401 on the next request. If a key is exposed, report it and it is revoked immediately.
Authentication
Send the key in the Authorization header of every request.
Authorization: Bearer thk_...| Key setting | Default | Effect |
|---|---|---|
| Prices | Off | When on, /v1/units includes price, price_per_sqm and currency. |
| Rate limit | 60 / minute | See Rate limits. |
Units
/v1/unitsReturns every villa in one response (69 today). No pagination. A polling interval of a few minutes is sufficient.
| Query parameter | Values | Default |
|---|---|---|
format | json, csv | json |
include_retired | true | Retired villas excluded |
curl -H "Authorization: Bearer $TARIN_KEY" \
https://api.tarin.keys.krd/v1/units
const res = await fetch('https://api.tarin.keys.krd/v1/units', {
headers: { Authorization: `Bearer ${process.env.TARIN_KEY}` },
});
const { units } = await res.json();
import os, requests
res = requests.get(
"https://api.tarin.keys.krd/v1/units",
headers={"Authorization": f"Bearer {os.environ['TARIN_KEY']}"},
timeout=30,
)
units = res.json()["units"]
Unit fields
Areas in square metres (m²). Prices in US dollars. Unknown fields must be ignored.
| Field | Type | Description |
|---|---|---|
id | string (UUID) | Permanent villa ID. Unchanged by renumbering. Use as the primary key. |
code | string | Commercial name, e.g. TH-101. |
number | integer | Number in the code, e.g. 101. |
kind | string | Always Villa. |
type.code | string | 650, 750 or 670. |
type.name | string | Hillside Villas A (650), Hillside Villas B (750), Floating Villas (670). |
group | string | Grouping; equal to type.name. First digit of the number: 1 = Hillside A, 2 = Hillside B, 3 = Floating. |
status | string | available, reserved, orally_reserved, sold, not_available. See Status values. |
tarin_status | string | Internal status before mapping. |
sellable_area_sqm | number | Total sellable area (built-up area). |
built_up_area_sqm | number | Same value as sellable_area_sqm. |
plot_area_sqm | number | Land plot area. Varies by villa. |
floors | string | Storeys, e.g. G+2. Villas are whole houses; there is no unit floor. |
floor_count | integer | Storeys as a number. |
bedrooms | integer | Bedrooms, excluding staff rooms. |
staff_rooms | integer | Staff bedrooms. |
bathrooms | integer | Bathrooms and enclosed WCs, including staff. |
price prices | number | null | List price. null when sold or unpublished. |
price_per_sqm prices | number | null | Rate per m² of the type's marketed size (650, 670 or 750 m²). price = rate × marketed size. |
currency prices | string | USD. |
brochure_pdf_url | string | Villa card PDF for the type (floor plans and areas). |
updated_at | string | ISO 8601 UTC time of the last change to the villa. |
extra.lift | boolean | Has a lift. |
extra.guest_wcs | integer | Ground-floor guest WCs. |
extra.floor_areas_sqm | object | Built-up area per storey: ground, first, second. |
extra.floating | boolean | Floating Villa (type 670). |
extra.waterfront | boolean | In the waterfront row. True for every Floating Villa. |
prices Returned only when prices are enabled on the key.
Status values
tarin_status | Meaning | status |
|---|---|---|
AVAILABLE | On the market. | available |
RESERVED | Held for a buyer by a sales agent. No payment. Can be released. | orally_reserved |
COMMITTED | Reservation deposit paid. Off the market until sold or cancelled. | reserved |
SOLD | Sold. | sold |
OCCUPIED | Sold and handed over. | sold |
RETIRED | Removed from the site plan. Returned only with include_retired=true. | not_available |
No other states exist (no "blocked", "on hold" or "under negotiation"). To display RESERVED and COMMITTED alike, map from tarin_status.
Example response
Truncated to one villa. Key with prices enabled.
{
"api_version": "1",
"generated_at": "2026-11-15T12:41:28.474Z",
"project": "Tarin Hills",
"area_unit": "sqm",
"currency": "USD",
"prices_included": true,
"count": 69,
"units": [
{
"id": "40000000-0000-4000-8000-000000000035",
"code": "TH-301",
"number": 301,
"kind": "Villa",
"type": { "code": "670", "name": "Floating Villas" },
"group": "Floating Villas",
"status": "available",
"tarin_status": "AVAILABLE",
"sellable_area_sqm": 847.15,
"built_up_area_sqm": 847.15,
"plot_area_sqm": 738,
"floors": "G+2",
"floor_count": 3,
"bedrooms": 4,
"staff_rooms": 2,
"bathrooms": 10,
"price": 971500,
"price_per_sqm": 1450,
"currency": "USD",
"brochure_pdf_url": "https://api.tarin.keys.krd/brochures/tarin-hills-villa-card-670.pdf",
"updated_at": "2026-11-15T12:31:10.383Z",
"extra": {
"lift": true,
"guest_wcs": 1,
"floor_areas_sqm": { "ground": 302.92, "first": 348.22, "second": 195.99 },
"floating": true,
"waterfront": true
}
}
]
}Without prices: price, price_per_sqm and currency are omitted and prices_included is false.
CSV
GET /v1/units?format=csv. One row per villa with a header row. UTF-8, comma-separated, CRLF line endings, values quoted when needed.
Nested fields are flattened: type_code, type_name, extra_lift, extra_guest_wcs, extra_floor_area_ground_sqm, extra_floor_area_first_sqm, extra_floor_area_second_sqm, extra_floating, extra_waterfront. Price columns are present only when prices are enabled.
Columns may be appended. Read columns by header name, not position.
Enquiries
/v1/enquiriesCreates an enquiry in the Tarin Hills sales inbox, marked with your partner name. Body: JSON (Content-Type: application/json), maximum 16 KB.
| Field | Type | Description |
|---|---|---|
name required | string | Enquirer's name. Max 200 characters. |
phone one of | string | Phone number, international format preferred (+964 750 123 4567). Max 40 characters. |
email one of | string | Email address. Max 254 characters. |
message | string | Free text. Max 4,000 characters. |
unit_id | string (UUID) | Villa enquired about, by id from /v1/units. Preferred over unit_code. |
unit_code | string | Villa enquired about, by code, e.g. TH-301. Omit both for a general enquiry. |
reference | string | Your ID for the enquiry. Max 200 characters. Makes the request idempotent: a repeat returns the original enquiry. |
language | string | Language the enquirer used, e.g. en, ar, ckb. |
source_url | string (URL) | Page the enquiry was made from. |
metadata | object | Any extra key-value data (campaign, channel, agent). Max 8 KB. Shown to the sales team as sent. |
one of At least one of phone and email is required. Unknown fields are rejected.
curl -X POST https://api.tarin.keys.krd/v1/enquiries \
-H "Authorization: Bearer $TARIN_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Sara Ahmed",
"phone": "+964 750 123 4567",
"email": "sara@example.com",
"message": "I would like to visit the show villa.",
"unit_code": "TH-301",
"reference": "lead-48213",
"metadata": { "campaign": "launch", "channel": "app" }
}'
const res = await fetch('https://api.tarin.keys.krd/v1/enquiries', {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.TARIN_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
name: 'Sara Ahmed',
phone: '+964 750 123 4567',
unit_code: 'TH-301',
reference: 'lead-48213',
}),
});
const enquiry = await res.json(); // 201 created, 200 already received
| Status | Body | When |
|---|---|---|
| 201 | id, status, unit_code, created_at | Enquiry created. |
| 200 | Same as 201 | reference already used by this key. The original enquiry is returned; nothing is created. |
| 400 | error.fields | Missing or invalid fields, an unknown field, or an unknown villa. |
{
"id": "502b0268-44f2-4ed9-ab2a-3d4ab07b5208",
"status": "received",
"unit_code": "TH-301",
"created_at": "2026-11-16T07:51:38.624Z"
}Rate limits
60 requests per minute per key, counted across all endpoints in fixed one-minute windows. Higher limits on request.
| Header | Description |
|---|---|
X-RateLimit-Limit | Requests allowed per minute. |
X-RateLimit-Remaining | Requests left in the current window. |
Retry-After | Seconds to wait. Sent with 429 and 503. |
Errors
{ "error": { "code": "invalid_request", "message": "One or more fields are missing or invalid.", "fields": ["phone_or_email"] } }| HTTP | code | Cause |
|---|---|---|
| 400 | bad_request | Unsupported format on /v1/units. |
| 400 | invalid_request | Invalid enquiry. fields lists the offending field names. |
| 401 | unauthorized | Missing, unregistered or revoked key. |
| 405 | method_not_allowed | Wrong HTTP method. |
| 413 | payload_too_large | Body over 16 KB. |
| 415 | unsupported_media_type | Body is not application/json. |
| 429 | rate_limited | Rate limit exceeded. Retry after Retry-After seconds. |
| 503 | unavailable | Temporary failure. Retry after Retry-After seconds. |
Versioning
| Change | Examples | Policy |
|---|---|---|
| Additive | New response field, new CSV column (appended), new optional parameter | Without notice, within /v1 |
| Breaking | Removed or renamed field, changed type or meaning, new status value, new required field | Only in /v2, announced in advance; /v1 remains available for an agreed period |
Support, key registration and revocation: your Tarin Hills contact.