Tarin Hills Partner API v1

Partner API

Read the Tarin Hills villa inventory and send enquiries from your channels. JSON over HTTPS, one key per partner.

GET https://api.tarin.keys.krd/v1/units
POST https://api.tarin.keys.krd/v1/enquiries

Overview

Base URL: https://api.tarin.keys.krd. All requests use HTTPS and a partner key.

MethodPathPurpose
GET/v1/unitsAll villas with status, areas, rooms and (optionally) prices. JSON or CSV.
POST/v1/enquiriesCreate 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.

  1. Generate a key: thk_ followed by 48 lowercase hexadecimal characters (24 random bytes).
  2. Store the key in your secret manager. It cannot be recovered from what you send us.
  3. Send your Tarin Hills contact the prefix (the first 12 characters, e.g. thk_1a2b3c4d) and the hash (64 hexadecimal characters). Neither is secret.
  4. 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)"
Rotation and revocation

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.

Header
Authorization: Bearer thk_...
Key settingDefaultEffect
PricesOffWhen on, /v1/units includes price, price_per_sqm and currency.
Rate limit60 / minuteSee Rate limits.

Units

GET/v1/units

Returns every villa in one response (69 today). No pagination. A polling interval of a few minutes is sufficient.

Query parameterValuesDefault
formatjson, csvjson
include_retiredtrueRetired villas excluded
curl -H "Authorization: Bearer $TARIN_KEY" \
  https://api.tarin.keys.krd/v1/units

Unit fields

Areas in square metres (m²). Prices in US dollars. Unknown fields must be ignored.

FieldTypeDescription
idstring (UUID)Permanent villa ID. Unchanged by renumbering. Use as the primary key.
codestringCommercial name, e.g. TH-101.
numberintegerNumber in the code, e.g. 101.
kindstringAlways Villa.
type.codestring650, 750 or 670.
type.namestringHillside Villas A (650), Hillside Villas B (750), Floating Villas (670).
groupstringGrouping; equal to type.name. First digit of the number: 1 = Hillside A, 2 = Hillside B, 3 = Floating.
statusstringavailable, reserved, orally_reserved, sold, not_available. See Status values.
tarin_statusstringInternal status before mapping.
sellable_area_sqmnumberTotal sellable area (built-up area).
built_up_area_sqmnumberSame value as sellable_area_sqm.
plot_area_sqmnumberLand plot area. Varies by villa.
floorsstringStoreys, e.g. G+2. Villas are whole houses; there is no unit floor.
floor_countintegerStoreys as a number.
bedroomsintegerBedrooms, excluding staff rooms.
staff_roomsintegerStaff bedrooms.
bathroomsintegerBathrooms and enclosed WCs, including staff.
price pricesnumber | nullList price. null when sold or unpublished.
price_per_sqm pricesnumber | nullRate per m² of the type's marketed size (650, 670 or 750 m²). price = rate × marketed size.
currency pricesstringUSD.
brochure_pdf_urlstringVilla card PDF for the type (floor plans and areas).
updated_atstringISO 8601 UTC time of the last change to the villa.
extra.liftbooleanHas a lift.
extra.guest_wcsintegerGround-floor guest WCs.
extra.floor_areas_sqmobjectBuilt-up area per storey: ground, first, second.
extra.floatingbooleanFloating Villa (type 670).
extra.waterfrontbooleanIn the waterfront row. True for every Floating Villa.

prices Returned only when prices are enabled on the key.

Status values

tarin_statusMeaningstatus
AVAILABLEOn the market.available
RESERVEDHeld for a buyer by a sales agent. No payment. Can be released.orally_reserved
COMMITTEDReservation deposit paid. Off the market until sold or cancelled.reserved
SOLDSold.sold
OCCUPIEDSold and handed over.sold
RETIREDRemoved 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.

200 OK · application/json
{
  "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

POST/v1/enquiries

Creates an enquiry in the Tarin Hills sales inbox, marked with your partner name. Body: JSON (Content-Type: application/json), maximum 16 KB.

FieldTypeDescription
name requiredstringEnquirer's name. Max 200 characters.
phone one ofstringPhone number, international format preferred (+964 750 123 4567). Max 40 characters.
email one ofstringEmail address. Max 254 characters.
messagestringFree text. Max 4,000 characters.
unit_idstring (UUID)Villa enquired about, by id from /v1/units. Preferred over unit_code.
unit_codestringVilla enquired about, by code, e.g. TH-301. Omit both for a general enquiry.
referencestringYour ID for the enquiry. Max 200 characters. Makes the request idempotent: a repeat returns the original enquiry.
languagestringLanguage the enquirer used, e.g. en, ar, ckb.
source_urlstring (URL)Page the enquiry was made from.
metadataobjectAny 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" }
  }'
StatusBodyWhen
201id, status, unit_code, created_atEnquiry created.
200Same as 201reference already used by this key. The original enquiry is returned; nothing is created.
400error.fieldsMissing or invalid fields, an unknown field, or an unknown villa.
201 Created · application/json
{
  "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.

HeaderDescription
X-RateLimit-LimitRequests allowed per minute.
X-RateLimit-RemainingRequests left in the current window.
Retry-AfterSeconds to wait. Sent with 429 and 503.

Errors

Error body
{ "error": { "code": "invalid_request", "message": "One or more fields are missing or invalid.", "fields": ["phone_or_email"] } }
HTTPcodeCause
400bad_requestUnsupported format on /v1/units.
400invalid_requestInvalid enquiry. fields lists the offending field names.
401unauthorizedMissing, unregistered or revoked key.
405method_not_allowedWrong HTTP method.
413payload_too_largeBody over 16 KB.
415unsupported_media_typeBody is not application/json.
429rate_limitedRate limit exceeded. Retry after Retry-After seconds.
503unavailableTemporary failure. Retry after Retry-After seconds.

Versioning

ChangeExamplesPolicy
AdditiveNew response field, new CSV column (appended), new optional parameterWithout notice, within /v1
BreakingRemoved or renamed field, changed type or meaning, new status value, new required fieldOnly in /v2, announced in advance; /v1 remains available for an agreed period

Support, key registration and revocation: your Tarin Hills contact.