{"openapi":"3.1.0","info":{"title":"iMatch Connect API","version":"1.0.0","description":"Partner API for iMatch — Dubai real-estate matchmaking. Authenticate with `Authorization: Bearer imc_live_…` (or `X-Api-Key`). Every response is `{ data, meta }` or `{ error: { code, message, details? } }`. `/v1` is frozen: fields are only ever added. A TEST key (`imc_test_…`) works against the same endpoints in sandbox mode — real reads with masked contacts, simulated writes, synthetic webhook events — and every response to it carries `meta.sandbox: true`."},"servers":[{"url":"https://api.imatch.ae/v1","description":"Front door"},{"url":"https://app.imatch.ae/api/v1","description":"Panel host (identical)"}],"tags":[{"name":"Account"},{"name":"Listings"},{"name":"Inquiries"},{"name":"Projects"},{"name":"Locations"},{"name":"Matches"},{"name":"Changes"},{"name":"Webhooks"},{"name":"Embeds"},{"name":"AI"},{"name":"Agent links"},{"name":"Sandbox"}],"security":[{"apiKey":[]}],"paths":{"/me":{"get":{"summary":"Who am I — verify a key and read limits + usage","description":"Requires any active key.","tags":["Account"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Partner, key and usage.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/Me"},"meta":{"type":"object"}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/openapi.json":{"get":{"summary":"This document","tags":["Account"],"security":[],"responses":{"200":{"description":"OpenAPI 3.1 JSON."}}}},"/postman.json":{"get":{"summary":"Postman collection (v2.1) generated from this document","description":"Import into Postman: one folder per tag, every operation with its parameters and an example body, bearer auth at collection level. Set the `apiKey` collection variable to your key; `baseUrl` defaults to the production server.","tags":["Account"],"security":[],"responses":{"200":{"description":"Postman Collection Format v2.1 JSON."}}}},"/listings":{"get":{"summary":"Search live listings","description":"Most listings in the market carry no photo of their own. When one does not and we can match its project to our catalogue, that project's photos are appended to `photos` with `kind: \"project\"` — those are pictures of the BUILDING or development, not of this unit. `project_id` and `project_photo_url` are returned on every listing we could match, with or without its own photos, so you can label the picture honestly or link through to the project.\n\nRequires the `listings_read` feature switch.","tags":["Listings"],"security":[{"apiKey":[]}],"parameters":[{"name":"as_agent","in":"query","required":false,"schema":{"type":"integer"},"description":"Act as the person behind this agent link, so ownership-aware reads return THEIR rows and the Copilot is theirs. The header `X-Connect-Agent` is accepted instead. A link id that is not yours, was revoked, whose iMatch account was deactivated, whose brokerage is no longer yours, or that is not a plain integer → 403 `agent_link_invalid`. A link the person granted narrower scopes than this call needs → 403 `agent_link_scope_denied`."},{"name":"page","in":"query","required":false,"schema":{"description":"1-based page, default 1","type":"integer","minimum":1,"maximum":9007199254740991},"description":"1-based page, default 1"},{"name":"per_page","in":"query","required":false,"schema":{"description":"1–100, default 25","type":"integer","minimum":1,"maximum":100},"description":"1–100, default 25"},{"name":"q","in":"query","required":false,"schema":{"description":"Free text over reference, project, community, area, description","type":"string","maxLength":200},"description":"Free text over reference, project, community, area, description"},{"name":"purpose","in":"query","required":false,"schema":{"description":"Sale | Rent","type":"string","maxLength":20},"description":"Sale | Rent"},{"name":"property_type","in":"query","required":false,"schema":{"type":"string","maxLength":50}},{"name":"area","in":"query","required":false,"schema":{"type":"string","maxLength":120}},{"name":"community","in":"query","required":false,"schema":{"type":"string","maxLength":120}},{"name":"project","in":"query","required":false,"schema":{"type":"string","maxLength":160}},{"name":"developer","in":"query","required":false,"schema":{"type":"string","maxLength":160}},{"name":"bedrooms","in":"query","required":false,"schema":{"description":"studio | 1 | 2 | … (exact); `5+` means five or more","type":"string","maxLength":10},"description":"studio | 1 | 2 | … (exact); `5+` means five or more"},{"name":"bathrooms","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":30}},{"name":"min_price","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"name":"max_price","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"name":"min_sqft","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"name":"max_sqft","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"name":"furnished","in":"query","required":false,"schema":{"type":"string","maxLength":40}},{"name":"completion_status","in":"query","required":false,"schema":{"description":"Ready | Off-Plan","type":"string","maxLength":40},"description":"Ready | Off-Plan"},{"name":"category","in":"query","required":false,"schema":{"description":"Normal | Distress — only honoured with distress_read","type":"string","maxLength":20},"description":"Normal | Distress — only honoured with distress_read"},{"name":"source","in":"query","required":false,"schema":{"type":"string","maxLength":60}},{"name":"updated_since","in":"query","required":false,"schema":{"type":"string","minLength":4,"maxLength":40,"description":"ISO 8601 date or date-time, e.g. 2026-09-01T00:00:00Z"},"description":"ISO 8601 date or date-time, e.g. 2026-09-01T00:00:00Z"},{"name":"created_since","in":"query","required":false,"schema":{"type":"string","minLength":4,"maxLength":40,"description":"ISO 8601 date or date-time, e.g. 2026-09-01T00:00:00Z"},"description":"ISO 8601 date or date-time, e.g. 2026-09-01T00:00:00Z"},{"name":"external_id","in":"query","required":false,"schema":{"description":"Your own id (only your rows)","type":"string","maxLength":200},"description":"Your own id (only your rows)"},{"name":"ids","in":"query","required":false,"schema":{"description":"Comma-separated iMatch ids (max 100)","type":"string","maxLength":1000},"description":"Comma-separated iMatch ids (max 100)"},{"name":"sort","in":"query","required":false,"schema":{"description":"Prefix with - for descending. Default -updated_at","type":"string","enum":["updated_at","-updated_at","created_at","-created_at","price","-price","discount_percent","-discount_percent"]},"description":"Prefix with - for descending. Default -updated_at"},{"name":"include","in":"query","required":false,"schema":{"description":"Comma-separated extras. `contact` adds agent.phone (charged as a reveal).","type":"string","maxLength":100},"description":"Comma-separated extras. `contact` adds agent.phone (charged as a reveal)."}],"responses":{"200":{"description":"Listings page.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Listing"}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"},"has_more":{"type":"boolean"}}}}}}}},"400":{"description":"Invalid query (`validation_error`, Zod issues in `details`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}},"post":{"summary":"Create or update listings (upsert on external_id)","description":"One listing object or `{ listings: [...] }` (max 50). Re-sending the same `external_id` updates the row. 200 when every item succeeded, 207 when some failed.\n\nRequires the `listings_write` feature switch.","tags":["Listings"],"security":[{"apiKey":[]}],"requestBody":{"required":true,"description":"One listing or a batch.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"listings":{"minItems":1,"type":"array","items":{"type":"object","properties":{"external_id":{"type":"string","minLength":1,"maxLength":200,"description":"Your own id — the upsert key"},"purpose":{"anyOf":[{"type":"string","pattern":"^(sale|rent)$","description":"Sale | Rent"},{"type":"null"}]},"property_type":{"description":"Apartment | Villa | Townhouse | Penthouse | Plot | Office | …","anyOf":[{"type":"string","maxLength":50},{"type":"null"}]},"location_id":{"description":"The iMatch place this listing is in (an id from /locations) — the preferred way to place a listing: it wins over everything else. Omit it (or send null) and the listing is placed from `external_ref`, then from area / community / project.","anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}]},"external_ref":{"description":"Place the listing by an OUTSIDE id instead — e.g. `{ \"source\": \"bayut\", \"id\": \"5003\" }` or a DLD project id. Needs the `locations_refs` feature; without it (or when no place carries the id) the listing is placed from its text, with a warning.","anyOf":[{"type":"object","properties":{"source":{"type":"string","enum":["bayut","dld_area","dld_master_project","dld_project","dld_building","legacy_area","legacy_community","legacy_project"]},"id":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"integer","minimum":0,"maximum":9007199254740991}]}},"required":["source","id"]},{"type":"null"}]},"bayut_location_id":{"description":"Shorthand for `external_ref: { source: \"bayut\", id }`. Needs `locations_refs`.","anyOf":[{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"integer","minimum":0,"maximum":9007199254740991}]},{"type":"null"}]},"area":{"description":"Dubai area, e.g. Dubai Marina (resolved against our vocabulary)","anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"community":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"project":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}]},"developer":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}]},"floor":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}]},"bedrooms":{"description":"Studio | 1 | 2 | … (0 = Studio)","anyOf":[{"anyOf":[{"type":"number"},{"type":"string","maxLength":20}]},{"type":"null"}]},"bathrooms":{"anyOf":[{"anyOf":[{"type":"number"},{"type":"string","maxLength":20}]},{"type":"null"}]},"bua_sqft":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"plot_sqft":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"selling_price":{"description":"AED","anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"rent_price":{"description":"AED per year","anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"furnished":{"description":"Furnished | Unfurnished | Semi","anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"completion_status":{"description":"Ready | Off-Plan","anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"view":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"title":{"description":"Prepended to description when present","anyOf":[{"type":"string","maxLength":300},{"type":"null"}]},"description":{"anyOf":[{"type":"string","maxLength":20000},{"type":"null"}]},"payment_plan":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"handover_date":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"service_charges":{"description":"AED per sqft per year","anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"permit_number":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"agent_name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"agent_phone":{"description":"The listing agent's WhatsApp number","anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"live_status":{"type":"string","enum":["Active","Unlisted","Sold"]},"photos":{"description":"Needs photos_write","maxItems":20,"type":"array","items":{"type":"object","properties":{"url":{"description":"Publicly fetchable image URL","type":"string","maxLength":2000,"format":"uri"},"base64":{"description":"Raw base64 (no data: prefix needed), ≤ 15 MB decoded","type":"string","minLength":1,"maxLength":21000000},"mime":{"description":"image/jpeg | image/png | … (base64 only)","type":"string","maxLength":80},"kind":{"description":"Default photo","type":"string","enum":["photo","floor_plan","master_plan"]}}}}},"required":["external_id"]}}},"required":["listings"]},{"type":"object","properties":{"external_id":{"type":"string","minLength":1,"maxLength":200,"description":"Your own id — the upsert key"},"purpose":{"anyOf":[{"type":"string","pattern":"^(sale|rent)$","description":"Sale | Rent"},{"type":"null"}]},"property_type":{"description":"Apartment | Villa | Townhouse | Penthouse | Plot | Office | …","anyOf":[{"type":"string","maxLength":50},{"type":"null"}]},"location_id":{"description":"The iMatch place this listing is in (an id from /locations) — the preferred way to place a listing: it wins over everything else. Omit it (or send null) and the listing is placed from `external_ref`, then from area / community / project.","anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}]},"external_ref":{"description":"Place the listing by an OUTSIDE id instead — e.g. `{ \"source\": \"bayut\", \"id\": \"5003\" }` or a DLD project id. Needs the `locations_refs` feature; without it (or when no place carries the id) the listing is placed from its text, with a warning.","anyOf":[{"type":"object","properties":{"source":{"type":"string","enum":["bayut","dld_area","dld_master_project","dld_project","dld_building","legacy_area","legacy_community","legacy_project"]},"id":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"integer","minimum":0,"maximum":9007199254740991}]}},"required":["source","id"]},{"type":"null"}]},"bayut_location_id":{"description":"Shorthand for `external_ref: { source: \"bayut\", id }`. Needs `locations_refs`.","anyOf":[{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"integer","minimum":0,"maximum":9007199254740991}]},{"type":"null"}]},"area":{"description":"Dubai area, e.g. Dubai Marina (resolved against our vocabulary)","anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"community":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"project":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}]},"developer":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}]},"floor":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}]},"bedrooms":{"description":"Studio | 1 | 2 | … (0 = Studio)","anyOf":[{"anyOf":[{"type":"number"},{"type":"string","maxLength":20}]},{"type":"null"}]},"bathrooms":{"anyOf":[{"anyOf":[{"type":"number"},{"type":"string","maxLength":20}]},{"type":"null"}]},"bua_sqft":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"plot_sqft":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"selling_price":{"description":"AED","anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"rent_price":{"description":"AED per year","anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"furnished":{"description":"Furnished | Unfurnished | Semi","anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"completion_status":{"description":"Ready | Off-Plan","anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"view":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"title":{"description":"Prepended to description when present","anyOf":[{"type":"string","maxLength":300},{"type":"null"}]},"description":{"anyOf":[{"type":"string","maxLength":20000},{"type":"null"}]},"payment_plan":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"handover_date":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"service_charges":{"description":"AED per sqft per year","anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"permit_number":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"agent_name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"agent_phone":{"description":"The listing agent's WhatsApp number","anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"live_status":{"type":"string","enum":["Active","Unlisted","Sold"]},"photos":{"description":"Needs photos_write","maxItems":20,"type":"array","items":{"type":"object","properties":{"url":{"description":"Publicly fetchable image URL","type":"string","maxLength":2000,"format":"uri"},"base64":{"description":"Raw base64 (no data: prefix needed), ≤ 15 MB decoded","type":"string","minLength":1,"maxLength":21000000},"mime":{"description":"image/jpeg | image/png | … (base64 only)","type":"string","maxLength":80},"kind":{"description":"Default photo","type":"string","enum":["photo","floor_plan","master_plan"]}}}}},"required":["external_id"]}]},"example":{"listings":[{"external_id":"CRM-1001","purpose":"Sale","property_type":"Apartment","area":"Dubai Marina","project":"Marina Gate","bedrooms":2,"bathrooms":2,"bua_sqft":1250,"selling_price":2500000,"furnished":"Unfurnished","completion_status":"Ready","view":"Marina","description":"Bright two-bed with full marina view, vacant on transfer.","agent_name":"Sara Khan","agent_phone":"+971500000001"}]}}}},"responses":{"200":{"description":"All items processed.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"external_id":{"type":"string"},"id":{"type":["integer","null"]},"reference_no":{"type":["string","null"]},"action":{"type":"string","enum":["created","updated","unlisted","noop"],"description":"`noop` on a POST = the row already held every value you sent (id and reference_no are still returned, the item counts as succeeded, nothing is re-matched). `noop` on a failed item is accompanied by `error_code`."},"warnings":{"type":"array","items":{"type":"string"}},"warning_codes":{"type":"array","items":{"type":"string"},"description":"Listings (POST items and PATCH) only: a stable code for each PLACEMENT warning in `warnings`, in the same order — `location_unknown` (location_id names no live place; ignored), `location_merged:<new id>` (our id was merged — placed on the keeper; store the new id), `location_conflict` (location_id and the outside id name different places — placed by location_id), `bayut_id_ignored` (external_ref was sent too), `external_ref_unknown_source`, `external_ref_unknown_id` (no live place carries it; ignored), `external_ref_feature_off` (needs `locations_refs`). Branch on these, not on the prose. Other warnings carry no code. Empty when there is nothing to say."},"error":{"type":"string","description":"Generic message when the item failed."},"error_code":{"type":"string","enum":["duplicate_external_id","constraint_violation","internal_error"],"description":"Stable code when the item failed — branch on this, not on `error`."},"twin":{"type":"object","description":"Present when a listing item carried BOTH `selling_price` and `rent_price`: a property offered for sale AND for rent is stored as two listings. This result is the SALE half; `twin` is the RENT half, stored under `<external_id>#rent` (read, PATCH or DELETE it by that id). A later item for the same external_id with only one price takes the rent half down; DELETE takes both down; a PATCH to the sale half's external_id updates both (rent_price goes to the rent half). Add-only, 2026-09-26.","properties":{"external_id":{"type":"string"},"id":{"type":["integer","null"]},"reference_no":{"type":["string","null"]},"action":{"type":"string","enum":["created","updated","unlisted","noop"]},"warnings":{"type":"array","items":{"type":"string"}},"error":{"type":"string"},"error_code":{"type":"string","enum":["duplicate_external_id","constraint_violation","internal_error"]},"warning_codes":{"type":"array","items":{"type":"string"},"description":"Placement warning codes, as on the result itself."}}}}}}}},"meta":{"type":"object","properties":{"received":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"}}}}}}}},"207":{"description":"Some items failed — see per-item `error`.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"external_id":{"type":"string"},"id":{"type":["integer","null"]},"reference_no":{"type":["string","null"]},"action":{"type":"string","enum":["created","updated","unlisted","noop"],"description":"`noop` on a POST = the row already held every value you sent (id and reference_no are still returned, the item counts as succeeded, nothing is re-matched). `noop` on a failed item is accompanied by `error_code`."},"warnings":{"type":"array","items":{"type":"string"}},"warning_codes":{"type":"array","items":{"type":"string"},"description":"Listings (POST items and PATCH) only: a stable code for each PLACEMENT warning in `warnings`, in the same order — `location_unknown` (location_id names no live place; ignored), `location_merged:<new id>` (our id was merged — placed on the keeper; store the new id), `location_conflict` (location_id and the outside id name different places — placed by location_id), `bayut_id_ignored` (external_ref was sent too), `external_ref_unknown_source`, `external_ref_unknown_id` (no live place carries it; ignored), `external_ref_feature_off` (needs `locations_refs`). Branch on these, not on the prose. Other warnings carry no code. Empty when there is nothing to say."},"error":{"type":"string","description":"Generic message when the item failed."},"error_code":{"type":"string","enum":["duplicate_external_id","constraint_violation","internal_error"],"description":"Stable code when the item failed — branch on this, not on `error`."},"twin":{"type":"object","description":"Present when a listing item carried BOTH `selling_price` and `rent_price`: a property offered for sale AND for rent is stored as two listings. This result is the SALE half; `twin` is the RENT half, stored under `<external_id>#rent` (read, PATCH or DELETE it by that id). A later item for the same external_id with only one price takes the rent half down; DELETE takes both down; a PATCH to the sale half's external_id updates both (rent_price goes to the rent half). Add-only, 2026-09-26.","properties":{"external_id":{"type":"string"},"id":{"type":["integer","null"]},"reference_no":{"type":["string","null"]},"action":{"type":"string","enum":["created","updated","unlisted","noop"]},"warnings":{"type":"array","items":{"type":"string"}},"error":{"type":"string"},"error_code":{"type":"string","enum":["duplicate_external_id","constraint_violation","internal_error"]},"warning_codes":{"type":"array","items":{"type":"string"},"description":"Placement warning codes, as on the result itself."}}}}}}}},"meta":{"type":"object","properties":{"received":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"}}}}}}}},"400":{"description":"Invalid body (`validation_error`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"413":{"description":"More than 50 items (`batch_too_large`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/listings/{id}":{"get":{"summary":"One listing by iMatch id","description":"Requires the `listings_read` feature switch.","tags":["Listings"],"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"iMatch listing id"},{"name":"include","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated. `contact` adds `agent.phone` and is charged as a reveal."}],"responses":{"200":{"description":"Listing.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/Listing"},"meta":{"type":"object"}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"404":{"description":"Not found or not live (`not_found`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/listings/by-external/{external_id}":{"get":{"summary":"One of your listings by your own external id","description":"Requires the `listings_read` feature switch.","tags":["Listings"],"security":[{"apiKey":[]}],"parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"Your external id"},{"name":"include","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated. `contact` adds `agent.phone` and is charged as a reveal."}],"responses":{"200":{"description":"Listing.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/Listing"},"meta":{"type":"object"}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"404":{"description":"No listing of yours carries that id (`not_found`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}},"patch":{"summary":"Partially update one of your listings","description":"`live_status: \"Sold\"` also sets `status` to Sold. Only rows you created through Connect.\n\nRequires the `listings_write` feature switch.","tags":["Listings"],"security":[{"apiKey":[]}],"parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"Your external id"}],"requestBody":{"required":true,"description":"Fields to change.","content":{"application/json":{"schema":{"type":"object","properties":{"purpose":{"anyOf":[{"type":"string","pattern":"^(sale|rent)$","description":"Sale | Rent"},{"type":"null"}]},"property_type":{"description":"Apartment | Villa | Townhouse | Penthouse | Plot | Office | …","anyOf":[{"type":"string","maxLength":50},{"type":"null"}]},"location_id":{"description":"The iMatch place this listing is in (an id from /locations) — the preferred way to place a listing: it wins over everything else. Omit it (or send null) and the listing is placed from `external_ref`, then from area / community / project.","anyOf":[{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},{"type":"null"}]},"external_ref":{"description":"Place the listing by an OUTSIDE id instead — e.g. `{ \"source\": \"bayut\", \"id\": \"5003\" }` or a DLD project id. Needs the `locations_refs` feature; without it (or when no place carries the id) the listing is placed from its text, with a warning.","anyOf":[{"type":"object","properties":{"source":{"type":"string","enum":["bayut","dld_area","dld_master_project","dld_project","dld_building","legacy_area","legacy_community","legacy_project"]},"id":{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"integer","minimum":0,"maximum":9007199254740991}]}},"required":["source","id"]},{"type":"null"}]},"bayut_location_id":{"description":"Shorthand for `external_ref: { source: \"bayut\", id }`. Needs `locations_refs`.","anyOf":[{"anyOf":[{"type":"string","minLength":1,"maxLength":64},{"type":"integer","minimum":0,"maximum":9007199254740991}]},{"type":"null"}]},"area":{"description":"Dubai area, e.g. Dubai Marina (resolved against our vocabulary)","anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"community":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"project":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}]},"developer":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}]},"floor":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}]},"bedrooms":{"description":"Studio | 1 | 2 | … (0 = Studio)","anyOf":[{"anyOf":[{"type":"number"},{"type":"string","maxLength":20}]},{"type":"null"}]},"bathrooms":{"anyOf":[{"anyOf":[{"type":"number"},{"type":"string","maxLength":20}]},{"type":"null"}]},"bua_sqft":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"plot_sqft":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"selling_price":{"description":"AED","anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"rent_price":{"description":"AED per year","anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"furnished":{"description":"Furnished | Unfurnished | Semi","anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"completion_status":{"description":"Ready | Off-Plan","anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"view":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"title":{"description":"Prepended to description when present","anyOf":[{"type":"string","maxLength":300},{"type":"null"}]},"description":{"anyOf":[{"type":"string","maxLength":20000},{"type":"null"}]},"payment_plan":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"handover_date":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"service_charges":{"description":"AED per sqft per year","anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"permit_number":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"agent_name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"agent_phone":{"description":"The listing agent's WhatsApp number","anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"live_status":{"type":"string","enum":["Active","Unlisted","Sold"]}}},"example":{"selling_price":2400000,"live_status":"Active"}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"external_id":{"type":"string"},"id":{"type":["integer","null"]},"reference_no":{"type":["string","null"]},"action":{"type":"string","enum":["created","updated","unlisted","noop"],"description":"`noop` on a POST = the row already held every value you sent (id and reference_no are still returned, the item counts as succeeded, nothing is re-matched). `noop` on a failed item is accompanied by `error_code`."},"warnings":{"type":"array","items":{"type":"string"}},"warning_codes":{"type":"array","items":{"type":"string"},"description":"Listings (POST items and PATCH) only: a stable code for each PLACEMENT warning in `warnings`, in the same order — `location_unknown` (location_id names no live place; ignored), `location_merged:<new id>` (our id was merged — placed on the keeper; store the new id), `location_conflict` (location_id and the outside id name different places — placed by location_id), `bayut_id_ignored` (external_ref was sent too), `external_ref_unknown_source`, `external_ref_unknown_id` (no live place carries it; ignored), `external_ref_feature_off` (needs `locations_refs`). Branch on these, not on the prose. Other warnings carry no code. Empty when there is nothing to say."},"error":{"type":"string","description":"Generic message when the item failed."},"error_code":{"type":"string","enum":["duplicate_external_id","constraint_violation","internal_error"],"description":"Stable code when the item failed — branch on this, not on `error`."},"twin":{"type":"object","description":"Present when a listing item carried BOTH `selling_price` and `rent_price`: a property offered for sale AND for rent is stored as two listings. This result is the SALE half; `twin` is the RENT half, stored under `<external_id>#rent` (read, PATCH or DELETE it by that id). A later item for the same external_id with only one price takes the rent half down; DELETE takes both down; a PATCH to the sale half's external_id updates both (rent_price goes to the rent half). Add-only, 2026-09-26.","properties":{"external_id":{"type":"string"},"id":{"type":["integer","null"]},"reference_no":{"type":["string","null"]},"action":{"type":"string","enum":["created","updated","unlisted","noop"]},"warnings":{"type":"array","items":{"type":"string"}},"error":{"type":"string"},"error_code":{"type":"string","enum":["duplicate_external_id","constraint_violation","internal_error"]},"warning_codes":{"type":"array","items":{"type":"string"},"description":"Placement warning codes, as on the result itself."}}}}},"meta":{"type":"object"}}}}}},"400":{"description":"Invalid body.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"404":{"description":"Not found (`not_found`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}},"delete":{"summary":"Unlist one of your listings (never deletes)","description":"Requires the `listings_write` feature switch.","tags":["Listings"],"security":[{"apiKey":[]}],"parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"Your external id"}],"responses":{"200":{"description":"Unlisted.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"external_id":{"type":"string"},"id":{"type":["integer","null"]},"reference_no":{"type":["string","null"]},"action":{"type":"string","enum":["created","updated","unlisted","noop"],"description":"`noop` on a POST = the row already held every value you sent (id and reference_no are still returned, the item counts as succeeded, nothing is re-matched). `noop` on a failed item is accompanied by `error_code`."},"warnings":{"type":"array","items":{"type":"string"}},"warning_codes":{"type":"array","items":{"type":"string"},"description":"Listings (POST items and PATCH) only: a stable code for each PLACEMENT warning in `warnings`, in the same order — `location_unknown` (location_id names no live place; ignored), `location_merged:<new id>` (our id was merged — placed on the keeper; store the new id), `location_conflict` (location_id and the outside id name different places — placed by location_id), `bayut_id_ignored` (external_ref was sent too), `external_ref_unknown_source`, `external_ref_unknown_id` (no live place carries it; ignored), `external_ref_feature_off` (needs `locations_refs`). Branch on these, not on the prose. Other warnings carry no code. Empty when there is nothing to say."},"error":{"type":"string","description":"Generic message when the item failed."},"error_code":{"type":"string","enum":["duplicate_external_id","constraint_violation","internal_error"],"description":"Stable code when the item failed — branch on this, not on `error`."},"twin":{"type":"object","description":"Present when a listing item carried BOTH `selling_price` and `rent_price`: a property offered for sale AND for rent is stored as two listings. This result is the SALE half; `twin` is the RENT half, stored under `<external_id>#rent` (read, PATCH or DELETE it by that id). A later item for the same external_id with only one price takes the rent half down; DELETE takes both down; a PATCH to the sale half's external_id updates both (rent_price goes to the rent half). Add-only, 2026-09-26.","properties":{"external_id":{"type":"string"},"id":{"type":["integer","null"]},"reference_no":{"type":["string","null"]},"action":{"type":"string","enum":["created","updated","unlisted","noop"]},"warnings":{"type":"array","items":{"type":"string"}},"error":{"type":"string"},"error_code":{"type":"string","enum":["duplicate_external_id","constraint_violation","internal_error"]},"warning_codes":{"type":"array","items":{"type":"string"},"description":"Placement warning codes, as on the result itself."}}}}},"meta":{"type":"object"}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"404":{"description":"Not found (`not_found`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/listings/{id}/photos":{"post":{"summary":"Attach photos / floor plans to one of your listings","description":"Up to 20 per call, each a public `url` or `base64` (image/*, ≤15 MB). Stored re-encoded as WebP. **Idempotent:** a photo already on the listing — the same `url` and `kind`, or the same image — is not added again and not downloaded again; the response still has one entry per photo you sent, in your order, pointing at the existing photo. `meta.added` counts what was really stored, `meta.skipped_duplicates` what was already there. A new photo keeps the `url` you sent as `source_url`; an image already on the listing under another url keeps its original `source_url` (use `PUT` to re-point it). If any photo fails, nothing is stored and `error.details.failed` names every one: `[{ index, url, reason, message }]`, `reason` ∈ `fetch_failed` · `timeout` · `unsupported_media` · `too_large` · `decode_failed` · `invalid`.\n\nRequires the `photos_write` feature switch.","tags":["Listings"],"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"iMatch listing id"}],"requestBody":{"required":true,"description":"Photos to attach.","content":{"application/json":{"schema":{"type":"object","properties":{"photos":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"object","properties":{"url":{"description":"Publicly fetchable image URL","type":"string","maxLength":2000,"format":"uri"},"base64":{"description":"Raw base64 (no data: prefix needed), ≤ 15 MB decoded","type":"string","minLength":1,"maxLength":21000000},"mime":{"description":"image/jpeg | image/png | … (base64 only)","type":"string","maxLength":80},"kind":{"description":"Default photo","type":"string","enum":["photo","floor_plan","master_plan"]}}}}},"required":["photos"]},"example":{"photos":[{"url":"https://cdn.example.com/photos/1001-1.jpg","kind":"photo"},{"url":"https://cdn.example.com/photos/1001-plan.png","kind":"floor_plan"}]}}}},"responses":{"200":{"description":"Stored photos.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"photos":{"type":"array","items":{"$ref":"#/components/schemas/Photo"}}}},"meta":{"type":"object"}}}}}},"400":{"description":"Invalid body, undecodable image, or a `url` that could not be fetched as an image (`photo_fetch_failed` — the upstream reason is never disclosed). `error.details.failed` names each failing photo.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"404":{"description":"Listing is not yours (`not_found`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"409":{"description":"The listing's photos changed while this call ran (`photos_changed`). Nothing was written — send it again.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"413":{"description":"Image over 15 MB (`payload_too_large`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"415":{"description":"Not an image (`unsupported_media`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}},"put":{"summary":"Replace a listing's photos with exactly this list","description":"Needs `photos_write` **and** `photos_replace` (off by default — check `GET /v1/me`). Makes the listing's photo set EXACTLY the list you send, in that order (0–100 photos; `[]` removes them all). For each photo, in order:\n\n1. a photo already on the listing with the same `url` **and** `kind` is **kept** — it is not downloaded again, and keeps its `id`;\n2. otherwise the `url` is fetched and re-encoded, and a photo already on the listing with the same image (same `kind`) is **kept** and learns your `url` as its `source_url` — this is how photos attached before `source_url` existed are matched, and how old duplicate copies disappear;\n3. otherwise it is **added**.\n\nEvery photo the listing held that was not kept is **removed**. A `url` that changes `kind` (photo → floor_plan) is a remove + add with a new `id`, never a kept photo. The same `url` twice in one body, or two urls that are the same image, is a `400 validation_error`.\n\n**All or nothing:** every photo is fetched before anything is written; if any fails, nothing changes and `error.details.failed` names each one (`index`, `url`, `reason`). Two calls on one listing never interleave. **Latency:** synchronous; at most 10 downloads run at once, each capped at 10 s plus a few seconds to re-encode, so the worst case is about 130 s for 100 new photos — typically seconds, and a repeat of an unchanged set downloads nothing. Set your client timeout to 180 s. **Not a listing write:** it does not refresh the listing's 21-day expiry and emits no webhook, exactly like `POST …/photos` and `DELETE …/photos/{photoId}`. Response `meta`: `kept`, `added`, `removed`. After `[]`, a read of the listing may show `kind: \"project\"` photos again — those are iMatch's pictures of the building, never yours, and are not affected by a replace.\n\nRequires the `photos_replace` feature switch.","tags":["Listings"],"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"iMatch listing id"}],"requestBody":{"required":true,"description":"The listing's complete photo set, in display order.","content":{"application/json":{"schema":{"type":"object","properties":{"photos":{"maxItems":100,"type":"array","items":{"type":"object","properties":{"url":{"description":"Publicly fetchable image URL","type":"string","maxLength":2000,"format":"uri"},"base64":{"description":"Raw base64 (no data: prefix needed), ≤ 15 MB decoded","type":"string","minLength":1,"maxLength":21000000},"mime":{"description":"image/jpeg | image/png | … (base64 only)","type":"string","maxLength":80},"kind":{"description":"Default photo","type":"string","enum":["photo","floor_plan","master_plan"]}}},"description":"The listing's full photo set in display order, 0–100. Anything the listing holds that is not in this list is deleted."}},"required":["photos"]},"example":{"photos":[{"url":"https://cdn.example.com/photos/1001-1.jpg","kind":"photo"},{"url":"https://cdn.example.com/photos/1001-plan.png","kind":"floor_plan"}]}}}},"responses":{"200":{"description":"The listing's photos after the replace, in display order (each with `source_url` and `position`).","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"listing_id":{"type":"integer"},"photos":{"type":"array","items":{"$ref":"#/components/schemas/Photo"}}}},"meta":{"type":"object"}}}}}},"400":{"description":"Invalid body, a repeated url or image (`validation_error`), or a photo that could not be fetched / decoded — `error.details.failed` names each.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"404":{"description":"Listing is not yours (`not_found`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"409":{"description":"The listing's photos changed while this call ran (`photos_changed`). Nothing was written — send it again.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"413":{"description":"An image over 15 MB, or over 1 MB after compression (`payload_too_large`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"415":{"description":"Not an image (`unsupported_media`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/listings/by-external/{external_id}/photos":{"put":{"summary":"Replace the photos of one of your listings, by your own external id","description":"Needs `photos_write` **and** `photos_replace` (off by default — check `GET /v1/me`). Makes the listing's photo set EXACTLY the list you send, in that order (0–100 photos; `[]` removes them all). For each photo, in order:\n\n1. a photo already on the listing with the same `url` **and** `kind` is **kept** — it is not downloaded again, and keeps its `id`;\n2. otherwise the `url` is fetched and re-encoded, and a photo already on the listing with the same image (same `kind`) is **kept** and learns your `url` as its `source_url` — this is how photos attached before `source_url` existed are matched, and how old duplicate copies disappear;\n3. otherwise it is **added**.\n\nEvery photo the listing held that was not kept is **removed**. A `url` that changes `kind` (photo → floor_plan) is a remove + add with a new `id`, never a kept photo. The same `url` twice in one body, or two urls that are the same image, is a `400 validation_error`.\n\n**All or nothing:** every photo is fetched before anything is written; if any fails, nothing changes and `error.details.failed` names each one (`index`, `url`, `reason`). Two calls on one listing never interleave. **Latency:** synchronous; at most 10 downloads run at once, each capped at 10 s plus a few seconds to re-encode, so the worst case is about 130 s for 100 new photos — typically seconds, and a repeat of an unchanged set downloads nothing. Set your client timeout to 180 s. **Not a listing write:** it does not refresh the listing's 21-day expiry and emits no webhook, exactly like `POST …/photos` and `DELETE …/photos/{photoId}`. Response `meta`: `kept`, `added`, `removed`. After `[]`, a read of the listing may show `kind: \"project\"` photos again — those are iMatch's pictures of the building, never yours, and are not affected by a replace.\n\nRequires the `photos_replace` feature switch.","tags":["Listings"],"security":[{"apiKey":[]}],"parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"Your external id"}],"requestBody":{"required":true,"description":"The listing's complete photo set, in display order.","content":{"application/json":{"schema":{"type":"object","properties":{"photos":{"maxItems":100,"type":"array","items":{"type":"object","properties":{"url":{"description":"Publicly fetchable image URL","type":"string","maxLength":2000,"format":"uri"},"base64":{"description":"Raw base64 (no data: prefix needed), ≤ 15 MB decoded","type":"string","minLength":1,"maxLength":21000000},"mime":{"description":"image/jpeg | image/png | … (base64 only)","type":"string","maxLength":80},"kind":{"description":"Default photo","type":"string","enum":["photo","floor_plan","master_plan"]}}},"description":"The listing's full photo set in display order, 0–100. Anything the listing holds that is not in this list is deleted."}},"required":["photos"]},"example":{"photos":[{"url":"https://cdn.example.com/photos/1001-1.jpg","kind":"photo"},{"url":"https://cdn.example.com/photos/1001-plan.png","kind":"floor_plan"}]}}}},"responses":{"200":{"description":"The listing's photos after the replace, in display order (each with `source_url` and `position`).","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"listing_id":{"type":"integer"},"photos":{"type":"array","items":{"$ref":"#/components/schemas/Photo"}}}},"meta":{"type":"object"}}}}}},"400":{"description":"Invalid body, a repeated url or image (`validation_error`), or a photo that could not be fetched / decoded — `error.details.failed` names each.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"404":{"description":"Listing is not yours (`not_found`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"409":{"description":"The listing's photos changed while this call ran (`photos_changed`). Nothing was written — send it again.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"413":{"description":"An image over 15 MB, or over 1 MB after compression (`payload_too_large`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"415":{"description":"Not an image (`unsupported_media`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/listings/{id}/photos/{photoId}":{"delete":{"summary":"Remove a photo from one of your listings","description":"Requires the `photos_write` feature switch.","tags":["Listings"],"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"iMatch listing id"},{"name":"photoId","in":"path","required":true,"schema":{"type":"integer"},"description":"Photo id"}],"responses":{"200":{"description":"Removed.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"id":{"type":"integer"},"deleted":{"type":"boolean"}}},"meta":{"type":"object"}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"404":{"description":"Not found (`not_found`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/distress":{"get":{"summary":"Distress deals (discounted listings)","description":"Same filters as `/listings`; `category` is forced to Distress and the discount fields are always present. Default sort: biggest discount first. Project photos and `project_id` / `project_photo_url` work exactly as on `/listings` — a `kind: \"project\"` photo is the building, not this unit.\n\nRequires the `distress_read` feature switch.","tags":["Listings"],"security":[{"apiKey":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"description":"1-based page, default 1","type":"integer","minimum":1,"maximum":9007199254740991},"description":"1-based page, default 1"},{"name":"per_page","in":"query","required":false,"schema":{"description":"1–100, default 25","type":"integer","minimum":1,"maximum":100},"description":"1–100, default 25"},{"name":"q","in":"query","required":false,"schema":{"description":"Free text over reference, project, community, area, description","type":"string","maxLength":200},"description":"Free text over reference, project, community, area, description"},{"name":"purpose","in":"query","required":false,"schema":{"description":"Sale | Rent","type":"string","maxLength":20},"description":"Sale | Rent"},{"name":"property_type","in":"query","required":false,"schema":{"type":"string","maxLength":50}},{"name":"area","in":"query","required":false,"schema":{"type":"string","maxLength":120}},{"name":"community","in":"query","required":false,"schema":{"type":"string","maxLength":120}},{"name":"project","in":"query","required":false,"schema":{"type":"string","maxLength":160}},{"name":"developer","in":"query","required":false,"schema":{"type":"string","maxLength":160}},{"name":"bedrooms","in":"query","required":false,"schema":{"description":"studio | 1 | 2 | … (exact); `5+` means five or more","type":"string","maxLength":10},"description":"studio | 1 | 2 | … (exact); `5+` means five or more"},{"name":"bathrooms","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":30}},{"name":"min_price","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"name":"max_price","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"name":"min_sqft","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"name":"max_sqft","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"name":"furnished","in":"query","required":false,"schema":{"type":"string","maxLength":40}},{"name":"completion_status","in":"query","required":false,"schema":{"description":"Ready | Off-Plan","type":"string","maxLength":40},"description":"Ready | Off-Plan"},{"name":"category","in":"query","required":false,"schema":{"description":"Normal | Distress — only honoured with distress_read","type":"string","maxLength":20},"description":"Normal | Distress — only honoured with distress_read"},{"name":"source","in":"query","required":false,"schema":{"type":"string","maxLength":60}},{"name":"updated_since","in":"query","required":false,"schema":{"type":"string","minLength":4,"maxLength":40,"description":"ISO 8601 date or date-time, e.g. 2026-09-01T00:00:00Z"},"description":"ISO 8601 date or date-time, e.g. 2026-09-01T00:00:00Z"},{"name":"created_since","in":"query","required":false,"schema":{"type":"string","minLength":4,"maxLength":40,"description":"ISO 8601 date or date-time, e.g. 2026-09-01T00:00:00Z"},"description":"ISO 8601 date or date-time, e.g. 2026-09-01T00:00:00Z"},{"name":"external_id","in":"query","required":false,"schema":{"description":"Your own id (only your rows)","type":"string","maxLength":200},"description":"Your own id (only your rows)"},{"name":"ids","in":"query","required":false,"schema":{"description":"Comma-separated iMatch ids (max 100)","type":"string","maxLength":1000},"description":"Comma-separated iMatch ids (max 100)"},{"name":"sort","in":"query","required":false,"schema":{"description":"Prefix with - for descending. Default -updated_at","type":"string","enum":["updated_at","-updated_at","created_at","-created_at","price","-price","discount_percent","-discount_percent"]},"description":"Prefix with - for descending. Default -updated_at"},{"name":"include","in":"query","required":false,"schema":{"description":"Comma-separated extras. `contact` adds agent.phone (charged as a reveal).","type":"string","maxLength":100},"description":"Comma-separated extras. `contact` adds agent.phone (charged as a reveal)."}],"responses":{"200":{"description":"Distress listings page.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Listing"}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"},"has_more":{"type":"boolean"}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/inquiries":{"get":{"summary":"Search live buyer inquiries","description":"Requires the `inquiries_read` feature switch.","tags":["Inquiries"],"security":[{"apiKey":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"description":"1-based page, default 1","type":"integer","minimum":1,"maximum":9007199254740991},"description":"1-based page, default 1"},{"name":"per_page","in":"query","required":false,"schema":{"description":"1–100, default 25","type":"integer","minimum":1,"maximum":100},"description":"1–100, default 25"},{"name":"q","in":"query","required":false,"schema":{"description":"Free text over reference, location, project, requirements","type":"string","maxLength":200},"description":"Free text over reference, location, project, requirements"},{"name":"purpose","in":"query","required":false,"schema":{"type":"string","maxLength":20}},{"name":"location","in":"query","required":false,"schema":{"description":"Matches location_wanted / preferred_communities","type":"string","maxLength":120},"description":"Matches location_wanted / preferred_communities"},{"name":"project","in":"query","required":false,"schema":{"type":"string","maxLength":160}},{"name":"property_type","in":"query","required":false,"schema":{"type":"string","maxLength":50}},{"name":"bedrooms","in":"query","required":false,"schema":{"type":"string","maxLength":10}},{"name":"min_budget","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"name":"max_budget","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"name":"updated_since","in":"query","required":false,"schema":{"type":"string","minLength":4,"maxLength":40,"description":"ISO 8601 date or date-time, e.g. 2026-09-01T00:00:00Z"},"description":"ISO 8601 date or date-time, e.g. 2026-09-01T00:00:00Z"},{"name":"created_since","in":"query","required":false,"schema":{"type":"string","minLength":4,"maxLength":40,"description":"ISO 8601 date or date-time, e.g. 2026-09-01T00:00:00Z"},"description":"ISO 8601 date or date-time, e.g. 2026-09-01T00:00:00Z"},{"name":"source","in":"query","required":false,"schema":{"type":"string","maxLength":60}},{"name":"external_id","in":"query","required":false,"schema":{"type":"string","maxLength":200}},{"name":"ids","in":"query","required":false,"schema":{"description":"Comma-separated iMatch ids (max 100)","type":"string","maxLength":1000},"description":"Comma-separated iMatch ids (max 100)"},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["updated_at","-updated_at","created_at","-created_at"]}},{"name":"include","in":"query","required":false,"schema":{"description":"Comma-separated extras. `contact` adds agent.phone (charged as a reveal).","type":"string","maxLength":100},"description":"Comma-separated extras. `contact` adds agent.phone (charged as a reveal)."}],"responses":{"200":{"description":"Inquiries page.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Inquiry"}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"},"has_more":{"type":"boolean"}}}}}}}},"400":{"description":"Invalid query.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}},"post":{"summary":"Create or update inquiries (upsert on external_id)","description":"One inquiry or `{ inquiries: [...] }` (max 50). Needs `purpose` and `location_wanted` or `project_wanted`. A new Active inquiry is matched against live listings automatically.\n\nRequires the `inquiries_write` feature switch.","tags":["Inquiries"],"security":[{"apiKey":[]}],"requestBody":{"required":true,"description":"One inquiry or a batch.","content":{"application/json":{"schema":{"anyOf":[{"type":"object","properties":{"inquiries":{"minItems":1,"type":"array","items":{"type":"object","properties":{"external_id":{"type":"string","minLength":1,"maxLength":200,"description":"Your own id — the upsert key"},"purpose":{"type":"string","pattern":"^(sale|rent)$","description":"Sale | Rent"},"location_wanted":{"description":"Area(s) the buyer wants — required unless project_wanted","anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"preferred_communities":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]},"project_wanted":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}]},"developer_wanted":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}]},"property_type_wanted":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}]},"bedrooms_wanted":{"description":"Studio | 1 | 2-3 | …","anyOf":[{"anyOf":[{"type":"number"},{"type":"string","maxLength":20}]},{"type":"null"}]},"bathrooms_wanted":{"anyOf":[{"anyOf":[{"type":"number"},{"type":"string","maxLength":20}]},{"type":"null"}]},"min_size_sqft":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"max_size_sqft":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"budget_min":{"description":"AED","anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"budget_max":{"description":"AED","anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"currency":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"preferred_status":{"description":"Ready | Off-Plan","anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"handover_preference":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}]},"preferred_type":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}]},"furnished_preference":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"view_preference":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"floor_preference":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"vacancy_preference":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"payment_plan_preference":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"special_requirements":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}]},"agent_name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"agent_phone":{"description":"The agent's WhatsApp number","anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"live_status":{"type":"string","enum":["Active","Unlisted"]}},"required":["external_id","purpose"]}}},"required":["inquiries"]},{"type":"object","properties":{"external_id":{"type":"string","minLength":1,"maxLength":200,"description":"Your own id — the upsert key"},"purpose":{"type":"string","pattern":"^(sale|rent)$","description":"Sale | Rent"},"location_wanted":{"description":"Area(s) the buyer wants — required unless project_wanted","anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"preferred_communities":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]},"project_wanted":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}]},"developer_wanted":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}]},"property_type_wanted":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}]},"bedrooms_wanted":{"description":"Studio | 1 | 2-3 | …","anyOf":[{"anyOf":[{"type":"number"},{"type":"string","maxLength":20}]},{"type":"null"}]},"bathrooms_wanted":{"anyOf":[{"anyOf":[{"type":"number"},{"type":"string","maxLength":20}]},{"type":"null"}]},"min_size_sqft":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"max_size_sqft":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"budget_min":{"description":"AED","anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"budget_max":{"description":"AED","anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"currency":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"preferred_status":{"description":"Ready | Off-Plan","anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"handover_preference":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}]},"preferred_type":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}]},"furnished_preference":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"view_preference":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"floor_preference":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"vacancy_preference":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"payment_plan_preference":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"special_requirements":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}]},"agent_name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"agent_phone":{"description":"The agent's WhatsApp number","anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"live_status":{"type":"string","enum":["Active","Unlisted"]}},"required":["external_id","purpose"]}]},"example":{"inquiries":[{"external_id":"LEAD-77","purpose":"Sale","location_wanted":"Dubai Marina","property_type_wanted":"Apartment","bedrooms_wanted":"2","budget_min":2000000,"budget_max":2600000,"preferred_status":"Ready","agent_name":"Sara Khan","agent_phone":"+971500000001"}]}}}},"responses":{"200":{"description":"All items processed.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"external_id":{"type":"string"},"id":{"type":["integer","null"]},"reference_no":{"type":["string","null"]},"action":{"type":"string","enum":["created","updated","unlisted","noop"],"description":"`noop` on a POST = the row already held every value you sent (id and reference_no are still returned, the item counts as succeeded, nothing is re-matched). `noop` on a failed item is accompanied by `error_code`."},"warnings":{"type":"array","items":{"type":"string"}},"warning_codes":{"type":"array","items":{"type":"string"},"description":"Listings (POST items and PATCH) only: a stable code for each PLACEMENT warning in `warnings`, in the same order — `location_unknown` (location_id names no live place; ignored), `location_merged:<new id>` (our id was merged — placed on the keeper; store the new id), `location_conflict` (location_id and the outside id name different places — placed by location_id), `bayut_id_ignored` (external_ref was sent too), `external_ref_unknown_source`, `external_ref_unknown_id` (no live place carries it; ignored), `external_ref_feature_off` (needs `locations_refs`). Branch on these, not on the prose. Other warnings carry no code. Empty when there is nothing to say."},"error":{"type":"string","description":"Generic message when the item failed."},"error_code":{"type":"string","enum":["duplicate_external_id","constraint_violation","internal_error"],"description":"Stable code when the item failed — branch on this, not on `error`."},"twin":{"type":"object","description":"Present when a listing item carried BOTH `selling_price` and `rent_price`: a property offered for sale AND for rent is stored as two listings. This result is the SALE half; `twin` is the RENT half, stored under `<external_id>#rent` (read, PATCH or DELETE it by that id). A later item for the same external_id with only one price takes the rent half down; DELETE takes both down; a PATCH to the sale half's external_id updates both (rent_price goes to the rent half). Add-only, 2026-09-26.","properties":{"external_id":{"type":"string"},"id":{"type":["integer","null"]},"reference_no":{"type":["string","null"]},"action":{"type":"string","enum":["created","updated","unlisted","noop"]},"warnings":{"type":"array","items":{"type":"string"}},"error":{"type":"string"},"error_code":{"type":"string","enum":["duplicate_external_id","constraint_violation","internal_error"]},"warning_codes":{"type":"array","items":{"type":"string"},"description":"Placement warning codes, as on the result itself."}}}}}}}},"meta":{"type":"object","properties":{"received":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"}}}}}}}},"207":{"description":"Some items failed.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"results":{"type":"array","items":{"type":"object","properties":{"external_id":{"type":"string"},"id":{"type":["integer","null"]},"reference_no":{"type":["string","null"]},"action":{"type":"string","enum":["created","updated","unlisted","noop"],"description":"`noop` on a POST = the row already held every value you sent (id and reference_no are still returned, the item counts as succeeded, nothing is re-matched). `noop` on a failed item is accompanied by `error_code`."},"warnings":{"type":"array","items":{"type":"string"}},"warning_codes":{"type":"array","items":{"type":"string"},"description":"Listings (POST items and PATCH) only: a stable code for each PLACEMENT warning in `warnings`, in the same order — `location_unknown` (location_id names no live place; ignored), `location_merged:<new id>` (our id was merged — placed on the keeper; store the new id), `location_conflict` (location_id and the outside id name different places — placed by location_id), `bayut_id_ignored` (external_ref was sent too), `external_ref_unknown_source`, `external_ref_unknown_id` (no live place carries it; ignored), `external_ref_feature_off` (needs `locations_refs`). Branch on these, not on the prose. Other warnings carry no code. Empty when there is nothing to say."},"error":{"type":"string","description":"Generic message when the item failed."},"error_code":{"type":"string","enum":["duplicate_external_id","constraint_violation","internal_error"],"description":"Stable code when the item failed — branch on this, not on `error`."},"twin":{"type":"object","description":"Present when a listing item carried BOTH `selling_price` and `rent_price`: a property offered for sale AND for rent is stored as two listings. This result is the SALE half; `twin` is the RENT half, stored under `<external_id>#rent` (read, PATCH or DELETE it by that id). A later item for the same external_id with only one price takes the rent half down; DELETE takes both down; a PATCH to the sale half's external_id updates both (rent_price goes to the rent half). Add-only, 2026-09-26.","properties":{"external_id":{"type":"string"},"id":{"type":["integer","null"]},"reference_no":{"type":["string","null"]},"action":{"type":"string","enum":["created","updated","unlisted","noop"]},"warnings":{"type":"array","items":{"type":"string"}},"error":{"type":"string"},"error_code":{"type":"string","enum":["duplicate_external_id","constraint_violation","internal_error"]},"warning_codes":{"type":"array","items":{"type":"string"},"description":"Placement warning codes, as on the result itself."}}}}}}}},"meta":{"type":"object","properties":{"received":{"type":"integer"},"succeeded":{"type":"integer"},"failed":{"type":"integer"}}}}}}}},"400":{"description":"Invalid body.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"413":{"description":"More than 50 items (`batch_too_large`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/inquiries/{id}":{"get":{"summary":"One inquiry by iMatch id","description":"Requires the `inquiries_read` feature switch.","tags":["Inquiries"],"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"iMatch inquiry id"},{"name":"include","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated. `contact` adds `agent.phone` and is charged as a reveal."}],"responses":{"200":{"description":"Inquiry.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/Inquiry"},"meta":{"type":"object"}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"404":{"description":"Not found (`not_found`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/inquiries/by-external/{external_id}":{"get":{"summary":"One of your inquiries by your own external id","description":"Requires the `inquiries_read` feature switch.","tags":["Inquiries"],"security":[{"apiKey":[]}],"parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"Your external id"},{"name":"include","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated. `contact` adds `agent.phone` and is charged as a reveal."}],"responses":{"200":{"description":"Inquiry.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/Inquiry"},"meta":{"type":"object"}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"404":{"description":"Not found (`not_found`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}},"patch":{"summary":"Partially update one of your inquiries","description":"Requires the `inquiries_write` feature switch.","tags":["Inquiries"],"security":[{"apiKey":[]}],"parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"Your external id"}],"requestBody":{"required":true,"description":"Fields to change.","content":{"application/json":{"schema":{"type":"object","properties":{"purpose":{"type":"string","pattern":"^(sale|rent)$","description":"Sale | Rent"},"location_wanted":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"preferred_communities":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]},"project_wanted":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}]},"developer_wanted":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}]},"property_type_wanted":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}]},"bedrooms_wanted":{"anyOf":[{"anyOf":[{"type":"number"},{"type":"string","maxLength":20}]},{"type":"null"}]},"bathrooms_wanted":{"anyOf":[{"anyOf":[{"type":"number"},{"type":"string","maxLength":20}]},{"type":"null"}]},"min_size_sqft":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"max_size_sqft":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"budget_min":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"budget_max":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"currency":{"anyOf":[{"type":"string","maxLength":10},{"type":"null"}]},"preferred_status":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"handover_preference":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}]},"preferred_type":{"anyOf":[{"type":"string","maxLength":60},{"type":"null"}]},"furnished_preference":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"view_preference":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"floor_preference":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"vacancy_preference":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"payment_plan_preference":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"special_requirements":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}]},"agent_name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"agent_phone":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"live_status":{"type":"string","enum":["Active","Unlisted"]}}},"example":{"budget_max":2800000}}}},"responses":{"200":{"description":"Updated.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"external_id":{"type":"string"},"id":{"type":["integer","null"]},"reference_no":{"type":["string","null"]},"action":{"type":"string","enum":["created","updated","unlisted","noop"],"description":"`noop` on a POST = the row already held every value you sent (id and reference_no are still returned, the item counts as succeeded, nothing is re-matched). `noop` on a failed item is accompanied by `error_code`."},"warnings":{"type":"array","items":{"type":"string"}},"warning_codes":{"type":"array","items":{"type":"string"},"description":"Listings (POST items and PATCH) only: a stable code for each PLACEMENT warning in `warnings`, in the same order — `location_unknown` (location_id names no live place; ignored), `location_merged:<new id>` (our id was merged — placed on the keeper; store the new id), `location_conflict` (location_id and the outside id name different places — placed by location_id), `bayut_id_ignored` (external_ref was sent too), `external_ref_unknown_source`, `external_ref_unknown_id` (no live place carries it; ignored), `external_ref_feature_off` (needs `locations_refs`). Branch on these, not on the prose. Other warnings carry no code. Empty when there is nothing to say."},"error":{"type":"string","description":"Generic message when the item failed."},"error_code":{"type":"string","enum":["duplicate_external_id","constraint_violation","internal_error"],"description":"Stable code when the item failed — branch on this, not on `error`."},"twin":{"type":"object","description":"Present when a listing item carried BOTH `selling_price` and `rent_price`: a property offered for sale AND for rent is stored as two listings. This result is the SALE half; `twin` is the RENT half, stored under `<external_id>#rent` (read, PATCH or DELETE it by that id). A later item for the same external_id with only one price takes the rent half down; DELETE takes both down; a PATCH to the sale half's external_id updates both (rent_price goes to the rent half). Add-only, 2026-09-26.","properties":{"external_id":{"type":"string"},"id":{"type":["integer","null"]},"reference_no":{"type":["string","null"]},"action":{"type":"string","enum":["created","updated","unlisted","noop"]},"warnings":{"type":"array","items":{"type":"string"}},"error":{"type":"string"},"error_code":{"type":"string","enum":["duplicate_external_id","constraint_violation","internal_error"]},"warning_codes":{"type":"array","items":{"type":"string"},"description":"Placement warning codes, as on the result itself."}}}}},"meta":{"type":"object"}}}}}},"400":{"description":"Invalid body.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"404":{"description":"Not found (`not_found`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}},"delete":{"summary":"Unlist one of your inquiries (never deletes)","description":"Requires the `inquiries_write` feature switch.","tags":["Inquiries"],"security":[{"apiKey":[]}],"parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"Your external id"}],"responses":{"200":{"description":"Unlisted.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"external_id":{"type":"string"},"id":{"type":["integer","null"]},"reference_no":{"type":["string","null"]},"action":{"type":"string","enum":["created","updated","unlisted","noop"],"description":"`noop` on a POST = the row already held every value you sent (id and reference_no are still returned, the item counts as succeeded, nothing is re-matched). `noop` on a failed item is accompanied by `error_code`."},"warnings":{"type":"array","items":{"type":"string"}},"warning_codes":{"type":"array","items":{"type":"string"},"description":"Listings (POST items and PATCH) only: a stable code for each PLACEMENT warning in `warnings`, in the same order — `location_unknown` (location_id names no live place; ignored), `location_merged:<new id>` (our id was merged — placed on the keeper; store the new id), `location_conflict` (location_id and the outside id name different places — placed by location_id), `bayut_id_ignored` (external_ref was sent too), `external_ref_unknown_source`, `external_ref_unknown_id` (no live place carries it; ignored), `external_ref_feature_off` (needs `locations_refs`). Branch on these, not on the prose. Other warnings carry no code. Empty when there is nothing to say."},"error":{"type":"string","description":"Generic message when the item failed."},"error_code":{"type":"string","enum":["duplicate_external_id","constraint_violation","internal_error"],"description":"Stable code when the item failed — branch on this, not on `error`."},"twin":{"type":"object","description":"Present when a listing item carried BOTH `selling_price` and `rent_price`: a property offered for sale AND for rent is stored as two listings. This result is the SALE half; `twin` is the RENT half, stored under `<external_id>#rent` (read, PATCH or DELETE it by that id). A later item for the same external_id with only one price takes the rent half down; DELETE takes both down; a PATCH to the sale half's external_id updates both (rent_price goes to the rent half). Add-only, 2026-09-26.","properties":{"external_id":{"type":"string"},"id":{"type":["integer","null"]},"reference_no":{"type":["string","null"]},"action":{"type":"string","enum":["created","updated","unlisted","noop"]},"warnings":{"type":"array","items":{"type":"string"}},"error":{"type":"string"},"error_code":{"type":"string","enum":["duplicate_external_id","constraint_violation","internal_error"]},"warning_codes":{"type":"array","items":{"type":"string"},"description":"Placement warning codes, as on the result itself."}}}}},"meta":{"type":"object"}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"404":{"description":"Not found (`not_found`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/projects":{"get":{"summary":"Dubai projects feed","description":"Requires the `projects_read` feature switch.","tags":["Projects"],"security":[{"apiKey":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"description":"1-based page, default 1","type":"integer","minimum":1,"maximum":9007199254740991},"description":"1-based page, default 1"},{"name":"per_page","in":"query","required":false,"schema":{"description":"1–100, default 25","type":"integer","minimum":1,"maximum":100},"description":"1–100, default 25"},{"name":"q","in":"query","required":false,"schema":{"description":"Search text. With sort=relevance (the default when q is given) every word must appear in the name, an alias, the district, the area or the developer, best match first. With any other sort: name or alias contains q.","type":"string","maxLength":160},"description":"Search text. With sort=relevance (the default when q is given) every word must appear in the name, an alias, the district, the area or the developer, best match first. With any other sort: name or alias contains q."},{"name":"developer","in":"query","required":false,"schema":{"type":"string","maxLength":160}},{"name":"area","in":"query","required":false,"schema":{"type":"string","maxLength":120}},{"name":"district","in":"query","required":false,"schema":{"type":"string","maxLength":120}},{"name":"project_type","in":"query","required":false,"schema":{"type":"string","maxLength":60}},{"name":"property_type","in":"query","required":false,"schema":{"type":"string","maxLength":60}},{"name":"status","in":"query","required":false,"schema":{"type":"string","maxLength":60}},{"name":"sale_status","in":"query","required":false,"schema":{"type":"string","maxLength":60}},{"name":"completion_status","in":"query","required":false,"schema":{"type":"string","maxLength":60}},{"name":"min_price","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"name":"max_price","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"name":"updated_since","in":"query","required":false,"schema":{"type":"string","minLength":4,"maxLength":40,"description":"ISO 8601 date or date-time, e.g. 2026-09-01T00:00:00Z"},"description":"ISO 8601 date or date-time, e.g. 2026-09-01T00:00:00Z"},{"name":"sort","in":"query","required":false,"schema":{"description":"relevance (default when q is given; without q it lists by name) or name (default without q), min_price, expected_completion_date; prefix - for descending","type":"string","enum":["name","-name","min_price","-min_price","expected_completion_date","-expected_completion_date","relevance"]},"description":"relevance (default when q is given; without q it lists by name) or name (default without q), min_price, expected_completion_date; prefix - for descending"}],"responses":{"200":{"description":"Projects page.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Project"}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"},"has_more":{"type":"boolean"}}}}}}}},"400":{"description":"Invalid query.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/projects/{id}":{"get":{"summary":"Project detail","description":"`include=units` adds the developer's current unit list and requires the `units_read` feature.\n\nRequires the `projects_read` feature switch.","tags":["Projects"],"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"Project id"},{"name":"include","in":"query","required":false,"schema":{"type":"string"},"description":"`units`"}],"responses":{"200":{"description":"Project with optional `units`.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/Project"},"meta":{"type":"object"}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"404":{"description":"Not found (`not_found`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/areas":{"get":{"summary":"Areas with aliases","description":"Requires the `areas_read` feature switch.","tags":["Locations"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Every active area. Client-cacheable for an hour (`Cache-Control: private, max-age=3600`).","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Area"}},"meta":{"type":"object"}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/communities":{"get":{"summary":"Community hierarchy","description":"Requires the `areas_read` feature switch.","tags":["Locations"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Every community with its parent area. Client-cacheable for an hour (`Cache-Control: private, max-age=3600`).","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Community"}},"meta":{"type":"object"}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/locations/search":{"get":{"summary":"Search places in the locations tree","description":"Every place in the UAE sits in one tree: city → region → area → community → sub-community → cluster → building. Results are ranked: the whole query IS a name or an alias (`JVC`) → a name starting with it → a word starting with it → a close spelling. Each place carries its `breadcrumb` (the places it sits in, the city first), so a picker can show where it is. `meta.exact` is true when a name or alias matched the whole query. Area ids are the same ids `/v1/areas` returns. Client-cacheable for five minutes (`Cache-Control: private, max-age=300`).\n\nRequires the `areas_read` feature switch.","tags":["Locations"],"security":[{"apiKey":[]}],"parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string","minLength":2,"maxLength":120,"description":"What the user typed — a name, an abbreviation (`JVC`) or its start"},"description":"What the user typed — a name, an abbreviation (`JVC`) or its start"},{"name":"limit","in":"query","required":false,"schema":{"description":"Default 12, max 30","type":"integer","minimum":1,"maximum":30},"description":"Default 12, max 30"},{"name":"level","in":"query","required":false,"schema":{"description":"Comma list of levels to keep, e.g. `area,community`","type":"string","maxLength":120},"description":"Comma list of levels to keep, e.g. `area,community`"},{"name":"under","in":"query","required":false,"schema":{"description":"Only places inside this place id","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"description":"Only places inside this place id"}],"responses":{"200":{"description":"Places, best first.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Location"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"exact":{"type":"boolean"}}}}}}}},"400":{"description":"`q` shorter than 2 characters, or an unknown `level` (`validation_error`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/locations":{"get":{"summary":"The top of the locations tree","description":"Every place that sits in nothing — the eight emirate cities — A–Z. The starting point of a walk: continue with `/locations/{id}/children`, or take the whole tree at once with `/locations/export`. Client-cacheable for five minutes (`Cache-Control: private, max-age=300`).\n\nRequires the `areas_read` feature switch.","tags":["Locations"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"The cities.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Location"}},"meta":{"type":"object","properties":{"total":{"type":"integer"}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/locations/export":{"get":{"summary":"The whole locations tree, paged","description":"Parents before children (depth, then id), so every `parent_id` on a page was served on an earlier page or this one. Walk with `meta.next_cursor` until it is null. `meta.scope` says what you get: **compact** — every live place (the place fields plus `aliases`); **full** — with the `locations_refs` feature: EVERY node (merged signposts, retired places, schools and nurseries too) with every column we hold, every alias row with its `kind`, and every outside id (`refs`: Bayut, DLD, legacy — primary and secondary). Every page carries `ETag` = the version of what you see (`meta.version` too): send it back as `If-None-Match` and an unchanged tree answers `304 Not Modified` with no body. If the version on your last page differs from your first, the tree changed while you walked — walk again.\n\nRequires the `areas_read` feature switch.","tags":["Locations"],"security":[{"apiKey":[]}],"parameters":[{"name":"cursor","in":"query","required":false,"schema":{"description":"`next_cursor` from the previous page","type":"string","maxLength":300},"description":"`next_cursor` from the previous page"},{"name":"limit","in":"query","required":false,"schema":{"description":"Places per page. Default 1000, max 2000","type":"integer","minimum":1,"maximum":2000},"description":"Places per page. Default 1000, max 2000"},{"name":"If-None-Match","in":"header","required":false,"schema":{"type":"string"},"description":"The `ETag` of a page you already hold — an unchanged tree answers 304."}],"responses":{"200":{"description":"One page of places.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LocationExportPlace"}},"meta":{"type":"object","properties":{"total":{"type":"integer","description":"Places the whole walk serves"},"version":{"type":"string","description":"Opaque; equals the ETag without quotes"},"scope":{"type":"string","enum":["compact","full"]},"next_cursor":{"type":["string","null"]},"has_more":{"type":"boolean"}}}}}}},"headers":{"ETag":{"schema":{"type":"string"},"description":"The version of the tree this page belongs to"}}},"304":{"description":"Not modified — the tree is still the version you sent in `If-None-Match`. No body."},"400":{"description":"Invalid `limit` or `cursor` (`validation_error`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/locations/changes":{"get":{"summary":"The places that changed since a point — incremental sync of the tree","description":"Take `/locations/export` once, then keep your copy current with this feed. Every item is `{ id, change, at, merged_into_id, place }`: `change` is `created`, `updated` (the place, one of its aliases or outside ids, or a place above it — its breadcrumb — changed) or `deleted` (no longer a live place: switched off, or merged — `merged_into_id` says where; re-point what you stored). `place` is the place exactly as the export shows it: every field with the `locations_refs` feature (merged and retired nodes as they are, schools and nurseries included), the compact place otherwise (null when it is no longer a live place; compact never lists schools or nurseries). Ordered by `(updated_at, id)` with a strict cursor — nothing skipped or repeated. **Ten-minute safety lag:** changes from the last 10 minutes are held back and `next_cursor` never passes `now − 10 min` (`meta.until`), because a place-writing batch can run for minutes and its rows carry its start time. Start with `since` (an ISO date-time, or any cursor we issued); continue with `cursor` = `meta.next_cursor` (it wins when both are sent). With neither, the feed starts from the tree's beginning — prefer the export for a first copy. `GET /changes?types=locations` is the ids-only view of the same rows; the cursors are interchangeable. Read-only: the tree is never modified through the API.\n\nRequires the `areas_read` feature switch.","tags":["Locations"],"security":[{"apiKey":[]}],"parameters":[{"name":"since","in":"query","required":false,"schema":{"description":"Where to start: an ISO 8601 date-time, or a `next_cursor` you were given. Ignored when `cursor` is sent.","type":"string","minLength":1,"maxLength":2000},"description":"Where to start: an ISO 8601 date-time, or a `next_cursor` you were given. Ignored when `cursor` is sent."},{"name":"cursor","in":"query","required":false,"schema":{"description":"`meta.next_cursor` from your previous call — continue exactly where it stopped","type":"string","maxLength":2000},"description":"`meta.next_cursor` from your previous call — continue exactly where it stopped"},{"name":"limit","in":"query","required":false,"schema":{"description":"Places per page. Default 500, max 2000","type":"integer","minimum":1,"maximum":2000},"description":"Places per page. Default 500, max 2000"}],"responses":{"200":{"description":"One page of changed places.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LocationChange"}},"meta":{"type":"object","properties":{"scope":{"type":"string","enum":["compact","full"]},"next_cursor":{"type":"string","description":"Opaque; pass back as `cursor`. Store it even when the page was empty."},"has_more":{"type":"boolean","description":"True when the page filled `limit` — call again right away"},"limit":{"type":"integer"},"lag_minutes":{"type":"integer","description":"How far behind real time the feed runs (10)"},"until":{"type":"string","description":"The instant this page was read up to (now − lag), microseconds"}}}}}}}},"400":{"description":"An unreadable `since` / `cursor`, or `limit` out of range (`validation_error`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/locations/retired":{"get":{"summary":"Place ids that no longer answer as a place of their own","description":"Merged into another place (`merged_into` = the live survivor — re-point what you stored) or taken out of the tree (`merged_into: null`). The companion of the compact export for a CRM that stores our ids. Same version and conditional GET as the export's tree.\n\nRequires the `areas_read` feature switch.","tags":["Locations"],"security":[{"apiKey":[]}],"parameters":[{"name":"If-None-Match","in":"header","required":false,"schema":{"type":"string"},"description":"A version you already hold."}],"responses":{"200":{"description":"Every retired id.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/LocationRetired"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"version":{"type":"string"}}}}}}}},"304":{"description":"Not modified. No body."},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/locations/resolve":{"get":{"summary":"Where a listing with this location text would be placed","description":"The same reading `POST /listings` makes of the same `area` / `community` / `project` (when no `location_id` is sent): our area vocabulary, then the database's resolver — exact names, aliases and catalogue projects, Dubai first, never a fuzzy guess. `status` is `resolved` (one place), `ambiguous` (several fit — `place` is the one iMatch would choose, null when it would not) or `unresolved`. `conflicting_fields` names fields that point somewhere else — usually a text worth fixing. Check a placement before you push, or map your own location list once.\n\nRequires the `areas_read` feature switch.","tags":["Locations"],"security":[{"apiKey":[]}],"parameters":[{"name":"area","in":"query","required":false,"schema":{"description":"The listing's area text, exactly as you would send it to POST /listings","type":"string","maxLength":200},"description":"The listing's area text, exactly as you would send it to POST /listings"},{"name":"community","in":"query","required":false,"schema":{"description":"The listing's community text","type":"string","maxLength":200},"description":"The listing's community text"},{"name":"project","in":"query","required":false,"schema":{"description":"The listing's project or building text","type":"string","maxLength":200},"description":"The listing's project or building text"},{"name":"within","in":"query","required":false,"schema":{"description":"Only look inside this place id","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"description":"Only look inside this place id"}],"responses":{"200":{"description":"The placement.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/LocationResolve"},"meta":{"type":"object"}}}}}},"400":{"description":"No text sent, or `within` is not a live place (`validation_error`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/locations/by-ref/{source}/{external_id}":{"get":{"summary":"Our place for an outside location id","description":"A Bayut location id, a Dubai Land Department area / master project / project / building id, or the id of one of our older lists (`legacy_area` = `/areas` id, `legacy_community` = `/communities` id, `legacy_project`) → the place, with every field. A place merged since answers as its survivor. Off unless iMatch enabled `locations_refs` for you.\n\nRequires the `locations_refs` feature switch.","tags":["Locations"],"security":[{"apiKey":[]}],"parameters":[{"name":"source","in":"path","required":true,"schema":{"type":"string","enum":["bayut","dld_area","dld_master_project","dld_project","dld_building","legacy_area","legacy_community","legacy_project"]},"description":"Which system the id comes from"},{"name":"external_id","in":"path","required":true,"schema":{"type":"string"},"description":"The id in that system"}],"responses":{"200":{"description":"The place, every field.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/LocationFull"},"meta":{"type":"object","properties":{"source":{"type":"string"},"external_id":{"type":"string"}}}}}}}},"400":{"description":"Unknown `source`, or a malformed id (`validation_error`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"404":{"description":"No place carries that id (`not_found`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/locations/{id}":{"get":{"summary":"One place, the places it sits in, and the places inside it","description":"`node` is the place and its `aliases` (the other texts iMatch reads as it). With the `locations_refs` feature it is the FULL place: every column we hold, every alias row with its kind, every outside id — and any node the full export carries (a school, a retired place) answers too. `children` is the first page of the places directly inside, A–Z — continue with `/locations/{id}/children`. A merged place answers as the place it was merged into, with `meta.merged_from` set to the id you asked for — store the new id.\n\nRequires the `areas_read` feature switch.","tags":["Locations"],"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"Place id"}],"responses":{"200":{"description":"The place.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/LocationDetail"},"meta":{"type":"object","properties":{"merged_from":{"type":"integer"}}}}}}}},"400":{"description":"`id` is not a positive integer (`validation_error`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"404":{"description":"No place with that id, or it was retired (`not_found`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/locations/{id}/children":{"get":{"summary":"The places directly inside a place","description":"A–Z, keyset-paged: pass `meta.next_cursor` back as `cursor` until it is null. A merged id pages the place it was merged into (`meta.merged_from`).\n\nRequires the `areas_read` feature switch.","tags":["Locations"],"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"Place id"},{"name":"cursor","in":"query","required":false,"schema":{"description":"`next_cursor` from the previous page","type":"string","maxLength":300},"description":"`next_cursor` from the previous page"},{"name":"limit","in":"query","required":false,"schema":{"description":"Default 50, max 100","type":"integer","minimum":1,"maximum":100},"description":"Default 50, max 100"}],"responses":{"200":{"description":"One page of places.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Location"}},"meta":{"type":"object","properties":{"total":{"type":"integer"},"next_cursor":{"type":["string","null"]},"has_more":{"type":"boolean"},"merged_from":{"type":"integer"}}}}}}}},"400":{"description":"Invalid `id`, `limit` or `cursor` (`validation_error`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"404":{"description":"No place with that id, or it was retired (`not_found`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/embed/sessions":{"post":{"summary":"Mint an embed token for our tools and screens","description":"Call this from YOUR SERVER with your API key and hand the returned `token` to the browser — the key itself never reaches a page. `tools` names what the token may open: the creators `offer` and `poster` (feature `tools_embed`) and `copilot` (feature `copilot`), and the screens `listings` (`listings_read`), `projects` (`projects_read`) and `matches` (`matches_read`) — the same read switches the matching `/listings`, `/projects` and `/matches` endpoints need; a request naming several kinds must pass every switch. The partner must have at least one allowed origin (Limits → Allowed origins in iMatch Connect) or the call is refused with `no_allowed_origins`. Open `<embed_base>/<tool>?token=<token>` in an iframe on one of those origins, or use the SDK (`/connect/v1/connect.js`). Tokens live at most one hour; mint a new one when the page reloads. `listing.inline` opens the offer / poster tools on a listing that exists only in your CRM (never sent to `/listings`): its details are kept for the session only (never beyond the hour, never in `listings`), photos are fetched from your https URLs at render time, and what the agent saves carries your `external_id` as its reference. The Copilot tool ignores it. See Embeds & SDK → Inline listings. `agent_link_id` opens the session AS a linked person: the screens show their own data and the Copilot is theirs, continuing the same thread they see in the iMatch app and on WhatsApp. The `agent` block stays display-only either way — a name your CRM sends is not a login. See Agent links.\n\nRequires any active key.","tags":["Embeds"],"security":[{"apiKey":[]}],"requestBody":{"required":true,"description":"Which tools, optionally who is driving them and which listing to open — by reference, or inline.","content":{"application/json":{"schema":{"type":"object","properties":{"tools":{"description":"Which tools this session may open: offer, poster (need tools_embed), copilot (needs copilot), and the screens listings (listings_read), projects (projects_read), matches (matches_read).","minItems":1,"maxItems":6,"type":"array","items":{"type":"string","enum":["offer","poster","copilot","listings","projects","matches"]}},"agent":{"description":"The CRM user who will drive the tool. Optional.","type":"object","properties":{"name":{"description":"Shown as the author of what the tool creates","anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"phone":{"description":"The agent's WhatsApp number (E.164)","anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"external_id":{"description":"Your own id for this agent","anyOf":[{"type":"string","maxLength":200},{"type":"null"}]}}},"listing":{"description":"Pre-select a listing in the tool. Optional.","type":"object","properties":{"id":{"description":"iMatch listing id","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"external_id":{"description":"Your own listing id (must be one of yours)","type":"string","minLength":1,"maxLength":200},"inline":{"description":"A listing that lives only in your CRM — its details, for the offer / poster tools. On its own, never with id / external_id. Ignored by the Copilot tool.","type":"object","properties":{"external_id":{"type":"string","minLength":1,"maxLength":80,"description":"Your own id for this listing — the reference on what the tool creates"},"title":{"description":"Short name of the property (title or description required)","anyOf":[{"type":"string","maxLength":300},{"type":"null"}]},"description":{"anyOf":[{"type":"string","maxLength":4000},{"type":"null"}]},"purpose":{"anyOf":[{"type":"string","pattern":"^(sale|rent)$","description":"Sale | Rent"},{"type":"null"}]},"property_type":{"description":"Apartment | Villa | Townhouse | Penthouse | Plot | Office | …","anyOf":[{"type":"string","maxLength":50},{"type":"null"}]},"area":{"description":"Dubai area, e.g. Dubai Marina","anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"community":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"project":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}]},"developer":{"anyOf":[{"type":"string","maxLength":160},{"type":"null"}]},"floor":{"anyOf":[{"type":"string","maxLength":20},{"type":"null"}]},"bedrooms":{"description":"Studio | 1 | 2 | … (0 = Studio)","anyOf":[{"anyOf":[{"type":"number"},{"type":"string","maxLength":20}]},{"type":"null"}]},"bathrooms":{"anyOf":[{"anyOf":[{"type":"number"},{"type":"string","maxLength":20}]},{"type":"null"}]},"bua_sqft":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"plot_sqft":{"anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"selling_price":{"description":"AED","anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"rent_price":{"description":"AED per year","anyOf":[{"type":"number","minimum":0},{"type":"null"}]},"currency":{"default":"AED","description":"AED — the only currency the tools render today","type":"string","const":"AED"},"furnished":{"description":"Furnished | Unfurnished | Semi","anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"completion_status":{"description":"Ready | Off-Plan","anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"handover_date":{"anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"payment_plan":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}]},"view":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}]},"permit_number":{"anyOf":[{"type":"string","maxLength":100},{"type":"null"}]},"photos":{"description":"Up to 20, in the order the tools should show them","maxItems":20,"type":"array","items":{"type":"object","properties":{"url":{"type":"string","maxLength":2000,"format":"uri","description":"Publicly fetchable https image URL on your own CDN. Private and internal addresses are refused."},"kind":{"description":"Default photo","type":"string","enum":["photo","floor_plan","master_plan"]}},"required":["url"]}},"agent":{"description":"The listing agent as printed on the poster. Optional.","type":"object","properties":{"name":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"phone":{"description":"E.164","anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"brokerage":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}]}}}},"required":["external_id"]}}},"agent_link_id":{"description":"Open the tools AS the person behind this agent link: the screens show their own listings, inquiries and matches, and the Copilot is theirs. The `agent` block above stays display-only whether you send this or not — a name is not a login. Must be one of YOUR links, still active, on an account that is still active.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"ttl_sec":{"description":"Token lifetime in seconds, 60–3600 (default 3600)","type":"integer","minimum":60,"maximum":3600}},"required":["tools"]},"example":{"tools":["offer","poster"],"agent":{"name":"Sara Khan","phone":"+971500000001","external_id":"U-12"},"listing":{"external_id":"CRM-1001"},"ttl_sec":900},"examples":{"default":{"summary":"Typical request","value":{"tools":["offer","poster"],"agent":{"name":"Sara Khan","phone":"+971500000001","external_id":"U-12"},"listing":{"external_id":"CRM-1001"},"ttl_sec":900}},"inline":{"summary":"A listing that lives only in your CRM","value":{"tools":["offer","poster"],"agent":{"name":"Sara Khan","phone":"+971500000001","external_id":"U-12"},"listing":{"inline":{"external_id":"crm-listing-1001","title":"2BR in Marina Gate 2 with full marina view","purpose":"Sale","property_type":"Apartment","area":"Dubai Marina","project":"Marina Gate 2","developer":"Select Group","bedrooms":2,"bathrooms":3,"bua_sqft":1420,"selling_price":3200000,"completion_status":"Ready","furnished":"Unfurnished","view":"Marina","floor":"24","description":"Bright two-bedroom on a high floor, vacant on transfer.","photos":[{"url":"https://cdn.example-crm.com/listings/1001/hero.jpg"},{"url":"https://cdn.example-crm.com/listings/1001/plan.png","kind":"floor_plan"}],"agent":{"name":"Sara Khan","phone":"+971500000001","brokerage":"Acme Real Estate"}}},"ttl_sec":900}}}}}},"responses":{"201":{"description":"Token minted.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/EmbedSession"},"meta":{"type":"object"}}}}}},"400":{"description":"Invalid body (`validation_error`) — including an inline photo URL that is not https or points at a private address.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"404":{"description":"`listing.external_id` is not one of your listings (`not_found`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"413":{"description":"`listing.inline` is over 64 KB (`payload_too_large`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"503":{"description":"`listing.inline` cannot be held right now — the session store is unreachable (`inline_unavailable`). Retry, or mint by `external_id`.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/copilot/chat":{"post":{"summary":"Ask the iMatch Copilot (one turn)","description":"Runs the same Copilot brain the iMatch panel uses, as your partner identity: it searches and explains listings, buyer inquiries, projects, areas and DLD market data across the market. It is READ-ONLY here — it cannot create or change records, send WhatsApp messages, generate files or read account profiles (write through the REST API or the MCP write tools). Conversations are kept for 24 h from the last message, keyed by your partner + `conversation_id`; omit the id to start one, or pass your own. `actions` lists the records the answer is about with their REST URLs. `usage` reports tool calls and replayed history, not tokens. Separate budget: 30 messages per minute per partner (`rate_limited` with `Retry-After`).\n\nRequires the `copilot` feature switch.","tags":["AI"],"security":[{"apiKey":[]}],"requestBody":{"required":true,"description":"The message, optionally the conversation to continue and what the user is looking at.","content":{"application/json":{"schema":{"type":"object","properties":{"conversation_id":{"description":"Continue a conversation. Omit to start one (we mint an id); pass your own id to key the thread yourself. Unknown or expired (24 h idle) ids start fresh.","type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$"},"message":{"type":"string","minLength":1,"maxLength":4000,"description":"The user's message"},"context":{"description":"What the user is looking at in your CRM. Prompt context only — never consent, never a filter.","type":"object","properties":{"listing_id":{"description":"iMatch listing id the user is looking at","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"external_id":{"description":"Your own listing id (one of yours)","type":"string","minLength":1,"maxLength":200}}}},"required":["message"]},"example":{"conversation_id":"crm-thread-42","message":"Any two-bed under 2.5M in Dubai Marina?","context":{"external_id":"CRM-9"}}}}},"responses":{"200":{"description":"The reply.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/CopilotChat"},"meta":{"type":"object","properties":{"tool_calls":{"type":"integer"}}}}}}}},"400":{"description":"Invalid body (`validation_error`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"404":{"description":"`context` names a listing you cannot see (`not_found`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"500":{"description":"The AI backend failed (`internal_error`). Retry once; the conversation is unaffected.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/copilot/chat/stream":{"post":{"summary":"Ask the iMatch Copilot — Server-Sent Events","description":"Same request and same brain as `/copilot/chat`, delivered as `text/event-stream`. Frames: `: keepalive` comments every 10 s while tools run; `event: action` (one per record the answer is about); `event: token` (`{ text }`, sentence-sized pieces of the reply); `event: done` (the full `/copilot/chat` data object); `event: error` (`{ code, message }`). Today the brain answers in one piece, so `token` frames arrive together at the end of the turn — the stream's value is the keepalive during tool use; when the brain streams tokens the frames become progressive without a contract change. A bad body is a normal 400 envelope, not a stream.\n\nRequires the `copilot` feature switch.","tags":["AI"],"security":[{"apiKey":[]}],"requestBody":{"required":true,"description":"Same as /copilot/chat.","content":{"application/json":{"schema":{"type":"object","properties":{"conversation_id":{"description":"Continue a conversation. Omit to start one (we mint an id); pass your own id to key the thread yourself. Unknown or expired (24 h idle) ids start fresh.","type":"string","pattern":"^[A-Za-z0-9_-]{8,64}$"},"message":{"type":"string","minLength":1,"maxLength":4000,"description":"The user's message"},"context":{"description":"What the user is looking at in your CRM. Prompt context only — never consent, never a filter.","type":"object","properties":{"listing_id":{"description":"iMatch listing id the user is looking at","type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"external_id":{"description":"Your own listing id (one of yours)","type":"string","minLength":1,"maxLength":200}}}},"required":["message"]},"example":{"conversation_id":"crm-thread-42","message":"And which of those has a sea view?"}}}},"responses":{"200":{"description":"`text/event-stream` — see the frame list.","content":{"text/event-stream":{"schema":{"type":"string"}}}},"400":{"description":"Invalid body (`validation_error`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/mcp":{"post":{"summary":"MCP server — JSON-RPC 2.0 over Streamable HTTP (for Claude, ChatGPT, Cursor, …)","description":"Model Context Protocol, protocol version `2025-06-18`. Methods: `initialize`, `notifications/initialized`, `ping`, `tools/list`, `tools/call`; batch arrays are accepted (at most 20 messages; every message counts as one request against the key's limit and daily quota — once spent, the rest of the batch answers -32004). Responses are plain JSON (no server-initiated stream). Each tool runs the SAME code as the REST route it mirrors and needs the same feature switch — a missing switch is JSON-RPC error `-32003` (`feature_disabled`). Tools: `search_listings` (listings_read), `get_listing` (listings_read), `search_inquiries` (inquiries_read), `get_inquiry` (inquiries_read), `search_projects` (projects_read), `get_project` (projects_read), `list_areas` (areas_read), `search_locations` (areas_read), `get_location` (areas_read), `resolve_location` (areas_read), `get_location_by_ref` (locations_refs), `my_matches` (matches_read), `create_listing` (listings_write), `update_listing` (listings_write), `create_inquiry` (inquiries_write), `distress_deals` (distress_read), `list_webhooks` (webhooks). Configure a client with this URL and `Authorization: Bearer imc_live_…`, e.g. `claude mcp add --transport http imatch https://api.imatch.ae/mcp --header \"Authorization: Bearer <key>\"`.\n\nRequires any active key.","tags":["AI"],"security":[{"apiKey":[]}],"requestBody":{"required":true,"description":"A JSON-RPC 2.0 request, notification, or an array of them.","content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","method"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"]},"id":{"oneOf":[{"type":"string"},{"type":"integer"}],"description":"Absent on a notification"},"method":{"type":"string","enum":["initialize","notifications/initialized","ping","tools/list","tools/call"]},"params":{"type":"object"}}},"example":{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_listings","arguments":{"area":"Dubai Marina","bedrooms":"2","purpose":"Sale","per_page":5}}}}}},"responses":{"200":{"description":"JSON-RPC response (or array). Tool results carry `content[0].text` (compact JSON) and `structuredContent` (`{ data, meta }`, the REST envelope); `isError: true` marks a tool-level refusal such as `not_found`.","content":{"application/json":{"schema":{"type":"object","properties":{"jsonrpc":{"type":"string"},"id":{},"result":{"type":"object"},"error":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"},"data":{}}}}}}}},"202":{"description":"The body held only notifications."},"400":{"description":"Body is not JSON (`-32700`).","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}},"get":{"summary":"MCP — no stream to open; answers 405 with the connection hint","description":"Requires any active key.","tags":["AI"],"security":[{"apiKey":[]}],"responses":{"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"405":{"description":"Always. `Allow: POST, DELETE`; the message shows how to connect a client (`method_not_allowed`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}},"delete":{"summary":"MCP — end session (a no-op; every call is self-contained)","description":"Requires any active key.","tags":["AI"],"security":[{"apiKey":[]}],"responses":{"204":{"description":"Nothing to tear down."},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/matches":{"get":{"summary":"Matches on your own listings and inquiries","description":"EXACT matches only unless you send `include=nearby`: then NEARBY matches too (the right area, not the exact building), each marked `kind: \"nearby\"` / `is_nearby: true` — `meta.total` counts what you asked for. Show nearby matches apart from exact ones.\n\nRequires the `matches_read` feature switch.","tags":["Matches"],"security":[{"apiKey":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"description":"1-based page, default 1","type":"integer","minimum":1,"maximum":9007199254740991},"description":"1-based page, default 1"},{"name":"per_page","in":"query","required":false,"schema":{"description":"1–100, default 25","type":"integer","minimum":1,"maximum":100},"description":"1–100, default 25"},{"name":"since","in":"query","required":false,"schema":{"description":"Only matches created at/after this instant","type":"string","minLength":4,"maxLength":40},"description":"Only matches created at/after this instant"},{"name":"status","in":"query","required":false,"schema":{"type":"string","maxLength":40}},{"name":"side","in":"query","required":false,"schema":{"description":"Which side of the match is yours","type":"string","enum":["listing","inquiry"]},"description":"Which side of the match is yours"},{"name":"listing_id","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"inquiry_id","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"min_score","in":"query","required":false,"schema":{"type":"number","minimum":0,"maximum":100}},{"name":"include","in":"query","required":false,"schema":{"description":"Comma-separated extras. `contact` adds the other party's agent.phone (charged as a reveal). `nearby` adds NEARBY matches (the right area, not the exact building) — left out unless you ask; each match says which it is in `kind`.","type":"string","maxLength":100},"description":"Comma-separated extras. `contact` adds the other party's agent.phone (charged as a reveal). `nearby` adds NEARBY matches (the right area, not the exact building) — left out unless you ask; each match says which it is in `kind`."}],"responses":{"200":{"description":"Matches page.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Match"}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"},"has_more":{"type":"boolean"}}}}}}}},"400":{"description":"Invalid query.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/changes":{"get":{"summary":"What changed since your last call (ids only)","description":"Each requested type needs its own read feature (`listings_read`, `inquiries_read`, `projects_read`, `areas_read` for `locations`); with no `types` you get every one of listings / inquiries / projects you may read — `locations` only when you ask for it. Rows are ordered by `(updated_at, id)` and the cursor is strict, so nothing is skipped or repeated under concurrent writes. Safety lag: changes from the last 10 seconds are held back and `next_cursor` never advances past `now − 10 s`, so a write that took a few seconds to commit is still picked up on your next call — expect a row to appear at least 10 seconds after it changed, never before. Pass `meta.next_cursor` back as `since`; keep polling with the same cursor when nothing changed. `change` is one of created / updated / unlisted / sold / deleted — fetch the row through the read API for its fields. `types=locations` (2026-09-26): the places of the tree, `change` created / updated / deleted with `merged_into_id` on every row, held TEN MINUTES back instead of 10 seconds (a place-writing batch can run for minutes) — `GET /locations/changes` is the same feed with each place in full. Listings and inquiries you are not licensed to read (`allowed_sources`) never appear.\n\nRequires any active key.","tags":["Changes"],"security":[{"apiKey":[]}],"parameters":[{"name":"since","in":"query","required":false,"schema":{"description":"The `next_cursor` from your previous call, or an ISO 8601 date-time to start from.","type":"string","minLength":1,"maxLength":2000},"description":"The `next_cursor` from your previous call, or an ISO 8601 date-time to start from."},{"name":"types","in":"query","required":false,"schema":{"description":"Comma-separated: listings, inquiries, projects, locations. Default: listings, inquiries and projects you may read — `locations` only when you ask for it.","type":"string","maxLength":60},"description":"Comma-separated: listings, inquiries, projects, locations. Default: listings, inquiries and projects you may read — `locations` only when you ask for it."},{"name":"limit","in":"query","required":false,"schema":{"description":"Max rows per type, default and ceiling 500","type":"integer","minimum":1,"maximum":500},"description":"Max rows per type, default and ceiling 500"}],"responses":{"200":{"description":"Changes per requested type.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/ChangesData"},"meta":{"type":"object","properties":{"next_cursor":{"type":"string","description":"Opaque; pass as `since`."},"has_more":{"type":"boolean","description":"True when any type hit `limit` — call again with `next_cursor` right away."},"limit":{"type":"integer"},"types":{"type":"array","items":{"type":"string"}}}}}}}}},"400":{"description":"Bad `types` or an unreadable `since` (`validation_error`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/webhooks":{"get":{"summary":"Your webhooks","description":"Requires the `webhooks` feature switch.","tags":["Webhooks"],"security":[{"apiKey":[]}],"responses":{"200":{"description":"Every webhook, secrets never included.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Webhook"}},"meta":{"type":"object","properties":{"total":{"type":"integer"}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}},"post":{"summary":"Create a webhook (the signing secret is returned ONCE)","description":"We POST a JSON envelope `{ id, event, created_at, partner, data }` with headers `X-Connect-Event`, `X-Connect-Delivery-Id` and `X-Connect-Signature: t=<unix seconds>,v1=<hex>` where `v1 = HMAC-SHA256(secret, t + \".\" + rawBody)`. Verify in constant time and reject `t` older than 5 minutes. Respond 2xx within 10 s; anything else is retried at 1m, 5m, 30m, 2h and 12h, then marked failed. Fifty consecutive failed deliveries switch the webhook off. Deliveries are at-least-once — dedupe on `id`.\n\nEvents: `ping` — A test delivery you asked for. · `match.created` — A new match on one of your listings or inquiries — exact matches; nearby ones too only with the matches_nearby feature. · `listing.created` — One of your listings was created through Connect. · `listing.updated` — One of your listings was changed through Connect, or put back on the market. · `listing.unlisted` — One of your listings was taken off the market — by you, by expiry, or by iMatch. · `listing.sold` — One of your listings was marked sold — by you, or by iMatch. · `inquiry.created` — One of your inquiries was created through Connect. · `inquiry.updated` — One of your inquiries was changed through Connect, or re-opened. · `inquiry.unlisted` — One of your inquiries was closed — by you, by expiry, or by iMatch. · `distress.created` — A new distress deal went live (needs the distress feature). · `agent_link.connected` — One of your users connected their iMatch account. · `agent_link.revoked` — An agent link ended — by the agent, by you, by their brokerage, by iMatch, or because the account was deactivated. · `location.updated` — Places in the locations tree changed — created, renamed, moved, re-aliased, merged or retired (needs areas_read).\n\nRequires the `webhooks` feature switch.","tags":["Webhooks"],"security":[{"apiKey":[]}],"requestBody":{"required":true,"description":"HTTPS url, the events to receive (or `*`), optional description.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2000,"format":"uri","description":"Your HTTPS endpoint. Private, loopback and link-local hosts are refused; no credentials in the URL, no #fragment."},"events":{"description":"Events to receive. `*` means every event, present and future.","minItems":1,"maxItems":14,"type":"array","items":{"type":"string","enum":["ping","match.created","listing.created","listing.updated","listing.unlisted","listing.sold","inquiry.created","inquiry.updated","inquiry.unlisted","distress.created","agent_link.connected","agent_link.revoked","location.updated","*"]}},"description":{"description":"Free text for your own reference","anyOf":[{"type":"string","maxLength":300},{"type":"null"}]}},"required":["url","events"]},"example":{"url":"https://crm.example.com/imatch/webhook","events":["match.created","listing.updated","inquiry.created"],"description":"Production receiver"}}}},"responses":{"201":{"description":"Created. `secret` is present in this response only.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/Webhook"},"meta":{"type":"object"}}}}}},"400":{"description":"Invalid body, non-HTTPS url, or a host that is private / unresolvable (`validation_error`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"409":{"description":"More than 10 webhooks (`limit_reached`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/webhooks/{id}":{"patch":{"summary":"Change a webhook, or rotate its secret","description":"`rotate_secret: true` mints a new secret and returns it ONCE; the old one stops working immediately. Setting `active: true` also resets the consecutive-failure counter.\n\nRequires the `webhooks` feature switch.","tags":["Webhooks"],"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"Webhook id"}],"requestBody":{"required":true,"description":"Fields to change.","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","maxLength":2000,"format":"uri","description":"Your HTTPS endpoint. Private, loopback and link-local hosts are refused; no credentials in the URL, no #fragment."},"events":{"description":"Events to receive. `*` means every event, present and future.","minItems":1,"maxItems":14,"type":"array","items":{"type":"string","enum":["ping","match.created","listing.created","listing.updated","listing.unlisted","listing.sold","inquiry.created","inquiry.updated","inquiry.unlisted","distress.created","agent_link.connected","agent_link.revoked","location.updated","*"]}},"active":{"description":"Switch deliveries on/off without deleting","type":"boolean"},"description":{"anyOf":[{"type":"string","maxLength":300},{"type":"null"}]},"rotate_secret":{"description":"Mint a new signing secret; the old one stops working immediately","type":"boolean","const":true}}},"example":{"active":true}}}},"responses":{"200":{"description":"Updated (with `secret` only when rotated).","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/Webhook"},"meta":{"type":"object"}}}}}},"400":{"description":"Invalid body.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"404":{"description":"Not one of your webhooks (`not_found`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}},"delete":{"summary":"Delete a webhook and its delivery history","description":"Requires the `webhooks` feature switch.","tags":["Webhooks"],"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"Webhook id"}],"responses":{"200":{"description":"Deleted.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"id":{"type":"integer"},"deleted":{"type":"boolean"}}},"meta":{"type":"object"}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"404":{"description":"Not one of your webhooks (`not_found`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/webhooks/{id}/test":{"post":{"summary":"Send a test `ping` to a webhook","description":"Queues one `ping` delivery to this webhook regardless of its subscriptions. Poll `GET /webhooks/deliveries/{delivery_id}` for the outcome (status, response code, error).\n\nRequires the `webhooks` feature switch.","tags":["Webhooks"],"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"Webhook id"}],"responses":{"202":{"description":"Queued.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"delivery_id":{"type":"integer"},"enqueued":{"type":"boolean"}}},"meta":{"type":"object"}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"404":{"description":"Not one of your webhooks (`not_found`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/webhooks/deliveries":{"get":{"summary":"Delivery log","description":"Newest first. The list omits `payload`; the detail endpoint includes it.\n\nRequires the `webhooks` feature switch.","tags":["Webhooks"],"security":[{"apiKey":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"description":"1-based page, default 1","type":"integer","minimum":1,"maximum":9007199254740991},"description":"1-based page, default 1"},{"name":"per_page","in":"query","required":false,"schema":{"description":"1–100, default 25","type":"integer","minimum":1,"maximum":100},"description":"1–100, default 25"},{"name":"webhook_id","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["pending","in_flight","delivered","failed"]}},{"name":"event","in":"query","required":false,"schema":{"description":"One event name (`*` is not a filter)","type":"string","enum":["ping","match.created","listing.created","listing.updated","listing.unlisted","listing.sold","inquiry.created","inquiry.updated","inquiry.unlisted","distress.created","agent_link.connected","agent_link.revoked","location.updated","*"]},"description":"One event name (`*` is not a filter)"},{"name":"since","in":"query","required":false,"schema":{"description":"Only deliveries created at/after this instant","type":"string","minLength":4,"maxLength":40},"description":"Only deliveries created at/after this instant"}],"responses":{"200":{"description":"Deliveries page.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"},"has_more":{"type":"boolean"}}}}}}}},"400":{"description":"Invalid query.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/webhooks/deliveries/{id}":{"get":{"summary":"One delivery, with the envelope exactly as sent","description":"Requires the `webhooks` feature switch.","tags":["Webhooks"],"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"Delivery id"}],"responses":{"200":{"description":"Delivery.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/WebhookDelivery"},"meta":{"type":"object"}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"404":{"description":"Not one of your deliveries (`not_found`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/sandbox/events":{"post":{"summary":"Synthesise a webhook event (test keys only)","description":"Builds a realistic payload for `event` — from your own sandbox rows when you have any, else a canned sample — and delivers it to your TEST webhooks exactly like a live event: same envelope, same signature, same worker, plus `X-Connect-Mode: test`. `sample` is deep-merged over the generated `data` so you can shape it (≤ 16 KB). A live key answers 400 `live_key`. The event's feature gate is the live one (`match.created` needs `matches_read`, `distress.created` needs `distress_read`).\n\nRequires the `webhooks` feature switch.","tags":["Sandbox"],"security":[{"apiKey":[]}],"requestBody":{"required":true,"description":"The event to synthesise, with an optional `sample` override.","content":{"application/json":{"schema":{"type":"object","properties":{"event":{"type":"string","enum":["match.created","listing.created","listing.updated","listing.unlisted","listing.sold","inquiry.created","inquiry.updated","inquiry.unlisted","distress.created","location.updated"],"description":"Which event to synthesise"},"sample":{"description":"Optional: fields merged over the generated `data` (deep merge, ≤ 16 KB) — e.g. { listing: { selling_price: 1 } }","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["event"]},"example":{"event":"match.created","sample":{"match":{"score":92}}}}}},"responses":{"202":{"description":"Queued to every subscribed test webhook; `data` is what they will receive.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/SandboxEvent"},"meta":{"type":"object"}}}}}},"400":{"description":"Invalid body, or a live key (`live_key`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/agent-links/start":{"post":{"summary":"Ask one of your users to connect their iMatch account","description":"Call this from YOUR SERVER when the agent presses “Connect my iMatch account”. Store `link_id` against that seat and send the agent's BROWSER to `authorize_url`. They sign in to iMatch as themselves and agree, and we send them back to your `return_url` with `?link=ok&link_id=…` (or `?link=cancelled`). The token inside `authorize_url` is single-use, worth half an hour, and is never returned again — it is not a credential to keep. `email` is a hint for the consent screen: never stored, never matched against an iMatch account. `phone` is a hint AND a fence — still never stored (we keep a one-way fingerprint for the life of the request) and still able to find nobody, but an iMatch account signing in with a DIFFERENT verified WhatsApp number is refused, so a forwarded `authorize_url` cannot bind the wrong person to the seat. A TEST key gets a SANDBOX link that binds a synthetic agent — a sandbox key can never connect a real person.\n\nRequires any active key.","tags":["Agent links"],"security":[{"apiKey":[]}],"requestBody":{"required":true,"description":"Which of your users to connect.","content":{"application/json":{"schema":{"type":"object","properties":{"external_user_id":{"type":"string","minLength":1,"maxLength":200,"description":"YOUR id for the CRM user being connected. One live link per id."},"return_url":{"description":"Where we send the browser after the agent connects or cancels (we append `?link=ok&link_id=…` or `?link=cancelled`). Must be on one of your allowed origins.","type":"string","maxLength":2000,"format":"uri"},"display_name":{"description":"How that user is named in your CRM. Shown on the consent screen as your claim — it is never taken as identity.","anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"email":{"description":"Hint only. Never stored, never matched against an iMatch account.","anyOf":[{"type":"string","maxLength":200},{"type":"null"}]},"phone":{"description":"Optional fence, and the one thing worth sending. The number you believe this user has. It still finds nobody and grants nothing — but if the iMatch account that signs in has a DIFFERENT verified WhatsApp number, the connection is refused (`wrong_person`), which is what stops a forwarded authorize_url binding the wrong person to this seat. Never stored and never returned: we keep a one-way fingerprint for the life of the request. Omit it and any signed-in account may complete the link.","anyOf":[{"type":"string","maxLength":40},{"type":"null"}]},"scopes":{"description":"What to ask for. Default: all of them. Shown to the agent in plain words before they agree.","minItems":1,"type":"array","items":{"type":"string","enum":["profile","listings","inquiries","matches","copilot"]}}},"required":["external_user_id"]},"example":{"external_user_id":"U-12","display_name":"Sara Khan","phone":"+971501234567","return_url":"https://crm.example.com/settings/imatch?connected=1"}}}},"responses":{"201":{"description":"Link started.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/AgentLinkStart"},"meta":{"type":"object"}}}}}},"400":{"description":"Invalid body (`validation_error`), or `return_url` is not on one of your allowed origins (`return_url_not_allowed`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"409":{"description":"That `external_user_id` already has an active link (`seat_already_linked`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"503":{"description":"The request store is unreachable (`link_unavailable`). Retry — no token was minted.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/agent-links":{"get":{"summary":"List your agent links","description":"Yours only — the partner is taken from the key, never from the query. No phone or email is ever returned.\n\nRequires any active key.","tags":["Agent links"],"security":[{"apiKey":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"description":"1-based page, default 1","type":"integer","minimum":1,"maximum":9007199254740991},"description":"1-based page, default 1"},{"name":"per_page","in":"query","required":false,"schema":{"description":"1–100, default 25","type":"integer","minimum":1,"maximum":100},"description":"1–100, default 25"},{"name":"status","in":"query","required":false,"schema":{"description":"Filter by status","type":"string","enum":["pending","active","revoked","expired"]},"description":"Filter by status"},{"name":"external_user_id","in":"query","required":false,"schema":{"description":"Your own id for one CRM user","type":"string","maxLength":200},"description":"Your own id for one CRM user"}],"responses":{"200":{"description":"Links page.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgentLink"}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"},"has_more":{"type":"boolean"}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/agent-links/{id}":{"get":{"summary":"One agent link","description":"Requires any active key.","tags":["Agent links"],"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"Link id"}],"responses":{"200":{"description":"The link.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/AgentLink"},"meta":{"type":"object"}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"404":{"description":"Not one of your links (`not_found`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}},"delete":{"summary":"Disconnect an agent link","description":"Ends the link on the agent's behalf (`revoked_by: partner`). Idempotent: a link that was already ended answers 200 with `meta.revoked: false`. The agent can also disconnect it in iMatch, their brokerage admin can revoke it, and deactivating their iMatch account revokes it automatically.\n\nRequires any active key.","tags":["Agent links"],"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"Link id"}],"responses":{"200":{"description":"Ended (or already ended).","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"$ref":"#/components/schemas/AgentLink"},"meta":{"type":"object"}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"404":{"description":"Not one of your links (`not_found`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/me/listings":{"get":{"summary":"The linked agent's own listings","description":"The same search as `/listings`, narrowed to the person named by `as_agent`. Requires the link: an endpoint that answers for ONE person must know which person, and it will never fall back to the brokerage. Ownership is the agent link on the row — a listing that merely quotes their phone number is not theirs. Unlike `/listings`, this returns their rows in ANY state, including the ones they have NOT published (Unlisted, Sold) — that is what the consent screen promises them. Read `live_status` on each row to filter. Under a TEST key this returns the rows that key itself sent.\n\nRequires the `listings_read` feature switch.","tags":["Agent links"],"security":[{"apiKey":[]}],"parameters":[{"name":"as_agent","in":"query","required":false,"schema":{"type":"integer"},"description":"Act as the person behind this agent link, so ownership-aware reads return THEIR rows and the Copilot is theirs. The header `X-Connect-Agent` is accepted instead. A link id that is not yours, was revoked, whose iMatch account was deactivated, whose brokerage is no longer yours, or that is not a plain integer → 403 `agent_link_invalid`. A link the person granted narrower scopes than this call needs → 403 `agent_link_scope_denied`."},{"name":"page","in":"query","required":false,"schema":{"description":"1-based page, default 1","type":"integer","minimum":1,"maximum":9007199254740991},"description":"1-based page, default 1"},{"name":"per_page","in":"query","required":false,"schema":{"description":"1–100, default 25","type":"integer","minimum":1,"maximum":100},"description":"1–100, default 25"},{"name":"q","in":"query","required":false,"schema":{"description":"Free text over reference, project, community, area, description","type":"string","maxLength":200},"description":"Free text over reference, project, community, area, description"},{"name":"purpose","in":"query","required":false,"schema":{"description":"Sale | Rent","type":"string","maxLength":20},"description":"Sale | Rent"},{"name":"property_type","in":"query","required":false,"schema":{"type":"string","maxLength":50}},{"name":"area","in":"query","required":false,"schema":{"type":"string","maxLength":120}},{"name":"community","in":"query","required":false,"schema":{"type":"string","maxLength":120}},{"name":"project","in":"query","required":false,"schema":{"type":"string","maxLength":160}},{"name":"developer","in":"query","required":false,"schema":{"type":"string","maxLength":160}},{"name":"bedrooms","in":"query","required":false,"schema":{"description":"studio | 1 | 2 | … (exact); `5+` means five or more","type":"string","maxLength":10},"description":"studio | 1 | 2 | … (exact); `5+` means five or more"},{"name":"bathrooms","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":30}},{"name":"min_price","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"name":"max_price","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"name":"min_sqft","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"name":"max_sqft","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"name":"furnished","in":"query","required":false,"schema":{"type":"string","maxLength":40}},{"name":"completion_status","in":"query","required":false,"schema":{"description":"Ready | Off-Plan","type":"string","maxLength":40},"description":"Ready | Off-Plan"},{"name":"category","in":"query","required":false,"schema":{"description":"Normal | Distress — only honoured with distress_read","type":"string","maxLength":20},"description":"Normal | Distress — only honoured with distress_read"},{"name":"source","in":"query","required":false,"schema":{"type":"string","maxLength":60}},{"name":"updated_since","in":"query","required":false,"schema":{"type":"string","minLength":4,"maxLength":40,"description":"ISO 8601 date or date-time, e.g. 2026-09-01T00:00:00Z"},"description":"ISO 8601 date or date-time, e.g. 2026-09-01T00:00:00Z"},{"name":"created_since","in":"query","required":false,"schema":{"type":"string","minLength":4,"maxLength":40,"description":"ISO 8601 date or date-time, e.g. 2026-09-01T00:00:00Z"},"description":"ISO 8601 date or date-time, e.g. 2026-09-01T00:00:00Z"},{"name":"external_id","in":"query","required":false,"schema":{"description":"Your own id (only your rows)","type":"string","maxLength":200},"description":"Your own id (only your rows)"},{"name":"ids","in":"query","required":false,"schema":{"description":"Comma-separated iMatch ids (max 100)","type":"string","maxLength":1000},"description":"Comma-separated iMatch ids (max 100)"},{"name":"sort","in":"query","required":false,"schema":{"description":"Prefix with - for descending. Default -updated_at","type":"string","enum":["updated_at","-updated_at","created_at","-created_at","price","-price","discount_percent","-discount_percent"]},"description":"Prefix with - for descending. Default -updated_at"},{"name":"include","in":"query","required":false,"schema":{"description":"Comma-separated extras. `contact` adds agent.phone (charged as a reveal).","type":"string","maxLength":100},"description":"Comma-separated extras. `contact` adds agent.phone (charged as a reveal)."}],"responses":{"200":{"description":"Their listings.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Listing"}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"},"has_more":{"type":"boolean"}}}}}}}},"400":{"description":"No `as_agent` (`agent_link_required`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"409":{"description":"That account has no agent record yet (`no_agent_record`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/me/inquiries":{"get":{"summary":"The linked agent's own inquiries","description":"The same search as `/inquiries`, narrowed to the person named by `as_agent`. Requires the link. Returns their inquiries in ANY state, including closed ones — read `live_status` on each row to filter.\n\nRequires the `inquiries_read` feature switch.","tags":["Agent links"],"security":[{"apiKey":[]}],"parameters":[{"name":"as_agent","in":"query","required":false,"schema":{"type":"integer"},"description":"Act as the person behind this agent link, so ownership-aware reads return THEIR rows and the Copilot is theirs. The header `X-Connect-Agent` is accepted instead. A link id that is not yours, was revoked, whose iMatch account was deactivated, whose brokerage is no longer yours, or that is not a plain integer → 403 `agent_link_invalid`. A link the person granted narrower scopes than this call needs → 403 `agent_link_scope_denied`."},{"name":"page","in":"query","required":false,"schema":{"description":"1-based page, default 1","type":"integer","minimum":1,"maximum":9007199254740991},"description":"1-based page, default 1"},{"name":"per_page","in":"query","required":false,"schema":{"description":"1–100, default 25","type":"integer","minimum":1,"maximum":100},"description":"1–100, default 25"},{"name":"q","in":"query","required":false,"schema":{"description":"Free text over reference, location, project, requirements","type":"string","maxLength":200},"description":"Free text over reference, location, project, requirements"},{"name":"purpose","in":"query","required":false,"schema":{"type":"string","maxLength":20}},{"name":"location","in":"query","required":false,"schema":{"description":"Matches location_wanted / preferred_communities","type":"string","maxLength":120},"description":"Matches location_wanted / preferred_communities"},{"name":"project","in":"query","required":false,"schema":{"type":"string","maxLength":160}},{"name":"property_type","in":"query","required":false,"schema":{"type":"string","maxLength":50}},{"name":"bedrooms","in":"query","required":false,"schema":{"type":"string","maxLength":10}},{"name":"min_budget","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"name":"max_budget","in":"query","required":false,"schema":{"type":"number","minimum":0}},{"name":"updated_since","in":"query","required":false,"schema":{"type":"string","minLength":4,"maxLength":40,"description":"ISO 8601 date or date-time, e.g. 2026-09-01T00:00:00Z"},"description":"ISO 8601 date or date-time, e.g. 2026-09-01T00:00:00Z"},{"name":"created_since","in":"query","required":false,"schema":{"type":"string","minLength":4,"maxLength":40,"description":"ISO 8601 date or date-time, e.g. 2026-09-01T00:00:00Z"},"description":"ISO 8601 date or date-time, e.g. 2026-09-01T00:00:00Z"},{"name":"source","in":"query","required":false,"schema":{"type":"string","maxLength":60}},{"name":"external_id","in":"query","required":false,"schema":{"type":"string","maxLength":200}},{"name":"ids","in":"query","required":false,"schema":{"description":"Comma-separated iMatch ids (max 100)","type":"string","maxLength":1000},"description":"Comma-separated iMatch ids (max 100)"},{"name":"sort","in":"query","required":false,"schema":{"type":"string","enum":["updated_at","-updated_at","created_at","-created_at"]}},{"name":"include","in":"query","required":false,"schema":{"description":"Comma-separated extras. `contact` adds agent.phone (charged as a reveal).","type":"string","maxLength":100},"description":"Comma-separated extras. `contact` adds agent.phone (charged as a reveal)."}],"responses":{"200":{"description":"Their inquiries.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Inquiry"}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"},"has_more":{"type":"boolean"}}}}}}}},"400":{"description":"No `as_agent` (`agent_link_required`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"409":{"description":"That account has no agent record yet (`no_agent_record`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/me/matches":{"get":{"summary":"The linked agent's own matches","description":"Matches where EITHER side is theirs. The other party's contact is still a metered reveal (`include=contact`); their own side's number is free — it is their own. Requires the link. Exact matches only unless you send `include=nearby`, as on `GET /matches`.\n\nRequires the `matches_read` feature switch.","tags":["Agent links"],"security":[{"apiKey":[]}],"parameters":[{"name":"as_agent","in":"query","required":false,"schema":{"type":"integer"},"description":"Act as the person behind this agent link, so ownership-aware reads return THEIR rows and the Copilot is theirs. The header `X-Connect-Agent` is accepted instead. A link id that is not yours, was revoked, whose iMatch account was deactivated, whose brokerage is no longer yours, or that is not a plain integer → 403 `agent_link_invalid`. A link the person granted narrower scopes than this call needs → 403 `agent_link_scope_denied`."},{"name":"page","in":"query","required":false,"schema":{"description":"1-based page, default 1","type":"integer","minimum":1,"maximum":9007199254740991},"description":"1-based page, default 1"},{"name":"per_page","in":"query","required":false,"schema":{"description":"1–100, default 25","type":"integer","minimum":1,"maximum":100},"description":"1–100, default 25"},{"name":"since","in":"query","required":false,"schema":{"description":"Only matches created at/after this instant","type":"string","minLength":4,"maxLength":40},"description":"Only matches created at/after this instant"},{"name":"status","in":"query","required":false,"schema":{"type":"string","maxLength":40}},{"name":"side","in":"query","required":false,"schema":{"description":"Which side of the match is yours","type":"string","enum":["listing","inquiry"]},"description":"Which side of the match is yours"},{"name":"listing_id","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"inquiry_id","in":"query","required":false,"schema":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}},{"name":"min_score","in":"query","required":false,"schema":{"type":"number","minimum":0,"maximum":100}},{"name":"include","in":"query","required":false,"schema":{"description":"Comma-separated extras. `contact` adds the other party's agent.phone (charged as a reveal). `nearby` adds NEARBY matches (the right area, not the exact building) — left out unless you ask; each match says which it is in `kind`.","type":"string","maxLength":100},"description":"Comma-separated extras. `contact` adds the other party's agent.phone (charged as a reveal). `nearby` adds NEARBY matches (the right area, not the exact building) — left out unless you ask; each match says which it is in `kind`."}],"responses":{"200":{"description":"Their matches.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Match"}},"meta":{"type":"object","properties":{"page":{"type":"integer"},"per_page":{"type":"integer"},"total":{"type":"integer"},"has_more":{"type":"boolean"}}}}}}}},"400":{"description":"No `as_agent` (`agent_link_required`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"409":{"description":"That account has no agent record yet (`no_agent_record`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}},"/webhooks/deliveries/{id}/redeliver":{"post":{"summary":"Send a delivery again","description":"Resets the delivery to pending with a fresh retry budget and queues it. A delivery that succeeded less than a minute ago is refused.\n\nRequires the `webhooks` feature switch.","tags":["Webhooks"],"security":[{"apiKey":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"integer"},"description":"Delivery id"}],"responses":{"202":{"description":"Queued.","content":{"application/json":{"schema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"object","properties":{"delivery_id":{"type":"integer"},"enqueued":{"type":"boolean"}}},"meta":{"type":"object"}}}}}},"401":{"description":"Missing, unknown, revoked or expired key (`unauthorized` / `key_revoked` / `key_expired`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"403":{"description":"Partner disabled or feature not enabled (`partner_disabled` / `feature_disabled`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"404":{"description":"Not one of your deliveries (`not_found`).","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"409":{"description":"Delivered less than a minute ago (`too_soon`); `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}},"429":{"description":"Rate limit / daily quota / reveal quota exceeded (`rate_limited` / `quota_exceeded` / `reveal_quota_exceeded`). `Retry-After` is set.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"details":{}}}}}}}}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An `imc_live_…` key (or `imc_test_…` for the sandbox) issued by iMatch. `X-Api-Key: <key>` is accepted too."}},"schemas":{"Me":{"type":"object","properties":{"partner":{"type":"object","properties":{"slug":{"type":"string"},"name":{"type":"string"},"features":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"boolean"}},"limits":{"type":"object","properties":{"rate_limit_per_min":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"daily_quota":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"reveal_quota_month":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"allowed_sources":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}]}},"required":["rate_limit_per_min","daily_quota","reveal_quota_month","allowed_sources"],"additionalProperties":false}},"required":["slug","name","features","limits"],"additionalProperties":false},"key":{"type":"object","properties":{"name":{"type":"string"},"prefix":{"type":"string"},"mode":{"type":"string","enum":["live","test"],"description":"live = production; test = the sandbox (real reads, simulated writes, masked contacts)"},"expires_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"scopes":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Features this key is limited to; null = every feature the partner has"}},"required":["name","prefix","mode","expires_at","scopes"],"additionalProperties":false},"usage":{"type":"object","properties":{"calls_today":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Calls made today in this key's mode"},"reveals_this_month":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["calls_today","reveals_this_month"],"additionalProperties":false},"agent":{"description":"Present only when the call carried `?as_agent=<link_id>`. Never a phone, an email or an iMatch user id.","type":"object","properties":{"link_id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"external_user_id":{"type":"string","description":"Your own id for this CRM user"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The agent's name in iMatch, or the display name you supplied"},"scopes":{"type":"array","items":{"type":"string"}}},"required":["link_id","external_user_id","name","scopes"],"additionalProperties":false}},"required":["partner","key","usage"],"additionalProperties":false},"Listing":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"reference_no":{"anyOf":[{"type":"string"},{"type":"null"}]},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Your own id — only on rows you created"},"purpose":{"anyOf":[{"type":"string"},{"type":"null"}]},"property_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Normal | Distress (Distress only visible with distress_read)"},"location_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The place of the locations tree this listing is filed under (GET /locations/{id}); null while it is not placed"},"location":{"description":"That place, named, with the places it sits in — present on every API read and webhook payload","anyOf":[{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"},"level":{"type":"string","enum":["city","region","area","community","sub_community","cluster","building"]},"breadcrumb":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"},"level":{"type":"string","enum":["city","region","area","community","sub_community","cluster","building"]}},"required":["id","name","level"],"additionalProperties":false}},"refs":{"description":"With `locations_refs` only: the place's PRIMARY outside ids (its Bayut id, DLD ids, legacy ids)","type":"array","items":{"type":"object","properties":{"source":{"type":"string","enum":["bayut","dld_area","dld_master_project","dld_project","dld_building","legacy_area","legacy_community","legacy_project"]},"id":{"type":"string","description":"The place's id in that system"},"primary":{"type":"boolean","description":"The id that system itself uses for this place. A place can also answer to a secondary id (a duplicate that system once listed). Legacy ids are always primary."}},"required":["source","id","primary"],"additionalProperties":false}}},"required":["id","name","level","breadcrumb"],"additionalProperties":false},{"type":"null"}]},"area":{"anyOf":[{"type":"string"},{"type":"null"}]},"community":{"anyOf":[{"type":"string"},{"type":"null"}]},"project":{"anyOf":[{"type":"string"},{"type":"null"}]},"developer":{"anyOf":[{"type":"string"},{"type":"null"}]},"floor":{"anyOf":[{"type":"string"},{"type":"null"}]},"bedrooms":{"anyOf":[{"type":"string"},{"type":"null"}]},"bathrooms":{"anyOf":[{"type":"string"},{"type":"null"}]},"bua_sqft":{"anyOf":[{"type":"number"},{"type":"null"}]},"plot_sqft":{"anyOf":[{"type":"number"},{"type":"null"}]},"view":{"anyOf":[{"type":"string"},{"type":"null"}]},"furnished":{"anyOf":[{"type":"string"},{"type":"null"}]},"completion_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"handover_date":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"live_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"vacancy":{"anyOf":[{"type":"string"},{"type":"null"}]},"selling_price":{"anyOf":[{"type":"number"},{"type":"null"}]},"rent_price":{"anyOf":[{"type":"number"},{"type":"null"}]},"price_per_sqft":{"anyOf":[{"type":"number"},{"type":"null"}]},"service_charges":{"anyOf":[{"type":"number"},{"type":"null"}]},"roi_percent":{"anyOf":[{"type":"number"},{"type":"null"}]},"rental_income":{"anyOf":[{"type":"number"},{"type":"null"}]},"currency":{"anyOf":[{"type":"string"},{"type":"null"}]},"payment_plan":{"anyOf":[{"type":"string"},{"type":"null"}]},"paid_percent":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"ai_summary":{"anyOf":[{"type":"string"},{"type":"null"}]},"extra_details":{"anyOf":[{"type":"string"},{"type":"null"}]},"extra_features":{"anyOf":[{"type":"string"},{"type":"null"}]},"permit_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"date_listed":{"anyOf":[{"type":"string"},{"type":"null"}]},"expires_after":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"anyOf":[{"type":"string"},{"type":"null"}]},"photos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Positive = a photo on this listing. Negative = a project photo iMatch added; it has no id of its own and cannot be deleted."},"kind":{"type":"string","enum":["photo","floor_plan","master_plan","project"],"description":"photo | floor_plan | master_plan = this listing's own media. project = a photo of the BUILDING or development the listing is in, from the iMatch project catalogue — NOT a photo of this unit."},"url":{"type":"string"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The url you sent when this photo was attached (null for base64, for project photos, and for any photo attached before 2026-09-26 — Connect did not keep it until then). Lets you check what iMatch holds without re-sending."},"position":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"0-based place of this photo among the listing's OWN photos, in display order. null for project photos."}},"required":["id","kind","url","source_url","position"],"additionalProperties":false},"description":"This listing's own images first, always. If it has none and we could match its `project` to our catalogue, the project's photos are appended with kind=\"project\" — pictures of the building, not of this unit."},"project_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The iMatch project this listing was matched to, or null if we could not match one. Read it with GET /projects/{id}."},"project_photo_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The matched project's main photo — the BUILDING or development, not this unit. Present whether or not the listing has its own photos, so you can label it honestly. Null when no project matched or it has no photo."},"agent":{"type":"object","properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"brokerage":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"description":"Only with include=contact","anyOf":[{"type":"string"},{"type":"null"}]},"contact_withheld":{"description":"Present instead of a phone when this row's contact is not available through the API (code: contact_not_available_for_source). No reveal is charged.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]}},"required":["name","brokerage"],"additionalProperties":false},"url":{"type":"string","description":"The public page for this listing (viewable without an iMatch login) — the link to show in your CRM"},"distress_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"original_price":{"anyOf":[{"type":"number"},{"type":"null"}]},"market_price":{"anyOf":[{"type":"number"},{"type":"null"}]},"op_plus_dld":{"anyOf":[{"type":"number"},{"type":"null"}]},"discount_amount":{"anyOf":[{"type":"number"},{"type":"null"}]},"discount_percent":{"anyOf":[{"type":"number"},{"type":"null"}]},"seller_urgency":{"anyOf":[{"type":"string"},{"type":"null"}]},"total_on_transfer":{"anyOf":[{"type":"number"},{"type":"null"}]},"already_paid":{"anyOf":[{"type":"number"},{"type":"null"}]},"premium":{"anyOf":[{"type":"number"},{"type":"null"}]},"dld_fee":{"anyOf":[{"type":"number"},{"type":"null"}]},"commission":{"anyOf":[{"type":"number"},{"type":"null"}]},"pending_payment":{"anyOf":[{"type":"number"},{"type":"null"}]},"payment_notes":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","reference_no","external_id","purpose","property_type","category","location_id","area","community","project","developer","floor","bedrooms","bathrooms","bua_sqft","plot_sqft","view","furnished","completion_status","handover_date","status","live_status","vacancy","selling_price","rent_price","price_per_sqft","service_charges","roi_percent","rental_income","currency","payment_plan","paid_percent","description","ai_summary","extra_details","extra_features","permit_number","date_listed","expires_after","created_at","updated_at","source","photos","project_id","project_photo_url","agent","url"],"additionalProperties":false},"Inquiry":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"reference_no":{"anyOf":[{"type":"string"},{"type":"null"}]},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"purpose":{"anyOf":[{"type":"string"},{"type":"null"}]},"location_wanted":{"anyOf":[{"type":"string"},{"type":"null"}]},"preferred_communities":{"anyOf":[{"type":"string"},{"type":"null"}]},"project_wanted":{"anyOf":[{"type":"string"},{"type":"null"}]},"developer_wanted":{"anyOf":[{"type":"string"},{"type":"null"}]},"property_type_wanted":{"anyOf":[{"type":"string"},{"type":"null"}]},"bedrooms_wanted":{"anyOf":[{"type":"string"},{"type":"null"}]},"bathrooms_wanted":{"anyOf":[{"type":"string"},{"type":"null"}]},"min_size_sqft":{"anyOf":[{"type":"number"},{"type":"null"}]},"max_size_sqft":{"anyOf":[{"type":"number"},{"type":"null"}]},"budget_min":{"anyOf":[{"type":"number"},{"type":"null"}]},"budget_max":{"anyOf":[{"type":"number"},{"type":"null"}]},"currency":{"anyOf":[{"type":"string"},{"type":"null"}]},"preferred_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"handover_preference":{"anyOf":[{"type":"string"},{"type":"null"}]},"preferred_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"furnished_preference":{"anyOf":[{"type":"string"},{"type":"null"}]},"view_preference":{"anyOf":[{"type":"string"},{"type":"null"}]},"floor_preference":{"anyOf":[{"type":"string"},{"type":"null"}]},"vacancy_preference":{"anyOf":[{"type":"string"},{"type":"null"}]},"payment_plan_preference":{"anyOf":[{"type":"string"},{"type":"null"}]},"special_requirements":{"anyOf":[{"type":"string"},{"type":"null"}]},"ai_summary":{"anyOf":[{"type":"string"},{"type":"null"}]},"live_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"date_received":{"anyOf":[{"type":"string"},{"type":"null"}]},"expires_after":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"anyOf":[{"type":"string"},{"type":"null"}]},"agent":{"type":"object","properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"brokerage":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"description":"Only with include=contact","anyOf":[{"type":"string"},{"type":"null"}]},"contact_withheld":{"description":"Present instead of a phone when this row's contact is not available through the API (code: contact_not_available_for_source). No reveal is charged.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]}},"required":["name","brokerage"],"additionalProperties":false}},"required":["id","reference_no","external_id","purpose","location_wanted","preferred_communities","project_wanted","developer_wanted","property_type_wanted","bedrooms_wanted","bathrooms_wanted","min_size_sqft","max_size_sqft","budget_min","budget_max","currency","preferred_status","handover_preference","preferred_type","furnished_preference","view_preference","floor_preference","vacancy_preference","payment_plan_preference","special_requirements","ai_summary","live_status","date_received","expires_after","created_at","updated_at","source","agent"],"additionalProperties":false},"Project":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"},"slug":{"anyOf":[{"type":"string"},{"type":"null"}]},"developer":{"anyOf":[{"type":"string"},{"type":"null"}]},"developer_logo_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"area":{"type":"object","properties":{"id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"name":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","name"],"additionalProperties":false},"district":{"anyOf":[{"type":"string"},{"type":"null"}]},"project_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"property_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"sale_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"completion_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"expected_completion_date":{"anyOf":[{"type":"string"},{"type":"null"}]},"construction_progress_pct":{"anyOf":[{"type":"number"},{"type":"null"}]},"post_handover":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"ownership_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"furnishing":{"anyOf":[{"type":"string"},{"type":"null"}]},"has_escrow":{"anyOf":[{"type":"boolean"},{"type":"null"}]},"service_charge":{"anyOf":[{"type":"string"},{"type":"null"}]},"min_price_aed":{"anyOf":[{"type":"number"},{"type":"null"}]},"max_floor":{"anyOf":[{"type":"number"},{"type":"null"}]},"available_units":{"anyOf":[{"type":"number"},{"type":"null"}]},"latitude":{"anyOf":[{"type":"number"},{"type":"null"}]},"longitude":{"anyOf":[{"type":"number"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"amenities":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"icon_url":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name","icon_url"],"additionalProperties":false}},"payment_plan":{"type":"object","properties":{"stages":{"type":"array","items":{"type":"object","properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"stage_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"percentage":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["name","stage_type","percentage"],"additionalProperties":false}},"has_post_handover":{"type":"boolean"}},"required":["stages","has_post_handover"],"additionalProperties":false},"travel_times":{"anyOf":[{},{"type":"null"}]},"parking_plan":{"anyOf":[{},{"type":"null"}]},"photo_url":{"anyOf":[{"type":"string"},{"type":"null"}]},"gallery":{"type":"array","items":{"type":"string"}},"floor_plans":{"type":"array","items":{"type":"string"}},"masterplan":{"type":"array","items":{"type":"string"}},"documents":{"type":"array","items":{"type":"object","properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"type":"string"}},"required":["name","url"],"additionalProperties":false}},"aliases":{"type":"array","items":{"type":"string"}},"inventories_raw":{"anyOf":[{},{"type":"null"}]},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"url":{"type":"string","description":"The public project page on imatch.ae — the link to show in your CRM"},"units":{"description":"Detail only, with include=units","type":"array","items":{"type":"object","properties":{"unit_ref":{"anyOf":[{"type":"string"},{"type":"null"}]},"unit_no":{"anyOf":[{"type":"string"},{"type":"null"}]},"building":{"anyOf":[{"type":"string"},{"type":"null"}]},"floor":{"anyOf":[{"type":"string"},{"type":"null"}]},"unit_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"bedrooms":{"anyOf":[{"type":"number"},{"type":"null"}]},"bathrooms":{"anyOf":[{"type":"number"},{"type":"null"}]},"size_sqft":{"anyOf":[{"type":"number"},{"type":"null"}]},"size_sqm":{"anyOf":[{"type":"number"},{"type":"null"}]},"plot_size_sqft":{"anyOf":[{"type":"number"},{"type":"null"}]},"balcony_sqft":{"anyOf":[{"type":"number"},{"type":"null"}]},"view":{"anyOf":[{"type":"string"},{"type":"null"}]},"orientation":{"anyOf":[{"type":"string"},{"type":"null"}]},"parking":{"anyOf":[{"type":"string"},{"type":"null"}]},"price_aed":{"anyOf":[{"type":"number"},{"type":"null"}]},"price_per_sqft":{"anyOf":[{"type":"number"},{"type":"null"}]},"currency":{"anyOf":[{"type":"string"},{"type":"null"}]},"payment_plan_raw":{"anyOf":[{"type":"string"},{"type":"null"}]},"availability":{"anyOf":[{"type":"string"},{"type":"null"}]},"handover_date":{"anyOf":[{"type":"string"},{"type":"null"}]},"completion_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["unit_ref","unit_no","building","floor","unit_type","bedrooms","bathrooms","size_sqft","size_sqm","plot_size_sqft","balcony_sqft","view","orientation","parking","price_aed","price_per_sqft","currency","payment_plan_raw","availability","handover_date","completion_status","updated_at"],"additionalProperties":false}}},"required":["id","name","slug","developer","developer_logo_url","area","district","project_type","property_type","status","sale_status","completion_status","expected_completion_date","construction_progress_pct","post_handover","ownership_type","furnishing","has_escrow","service_charge","min_price_aed","max_floor","available_units","latitude","longitude","description","amenities","payment_plan","travel_times","parking_plan","photo_url","gallery","floor_plans","masterplan","documents","aliases","created_at","updated_at","url"],"additionalProperties":false},"Unit":{"type":"object","properties":{"unit_ref":{"anyOf":[{"type":"string"},{"type":"null"}]},"unit_no":{"anyOf":[{"type":"string"},{"type":"null"}]},"building":{"anyOf":[{"type":"string"},{"type":"null"}]},"floor":{"anyOf":[{"type":"string"},{"type":"null"}]},"unit_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"bedrooms":{"anyOf":[{"type":"number"},{"type":"null"}]},"bathrooms":{"anyOf":[{"type":"number"},{"type":"null"}]},"size_sqft":{"anyOf":[{"type":"number"},{"type":"null"}]},"size_sqm":{"anyOf":[{"type":"number"},{"type":"null"}]},"plot_size_sqft":{"anyOf":[{"type":"number"},{"type":"null"}]},"balcony_sqft":{"anyOf":[{"type":"number"},{"type":"null"}]},"view":{"anyOf":[{"type":"string"},{"type":"null"}]},"orientation":{"anyOf":[{"type":"string"},{"type":"null"}]},"parking":{"anyOf":[{"type":"string"},{"type":"null"}]},"price_aed":{"anyOf":[{"type":"number"},{"type":"null"}]},"price_per_sqft":{"anyOf":[{"type":"number"},{"type":"null"}]},"currency":{"anyOf":[{"type":"string"},{"type":"null"}]},"payment_plan_raw":{"anyOf":[{"type":"string"},{"type":"null"}]},"availability":{"anyOf":[{"type":"string"},{"type":"null"}]},"handover_date":{"anyOf":[{"type":"string"},{"type":"null"}]},"completion_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["unit_ref","unit_no","building","floor","unit_type","bedrooms","bathrooms","size_sqft","size_sqm","plot_size_sqft","balcony_sqft","view","orientation","parking","price_aed","price_per_sqft","currency","payment_plan_raw","availability","handover_date","completion_status","updated_at"],"additionalProperties":false},"Area":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"},"latitude":{"anyOf":[{"type":"number"},{"type":"null"}]},"longitude":{"anyOf":[{"type":"number"},{"type":"null"}]},"aliases":{"type":"array","items":{"type":"string"}}},"required":["id","name","latitude","longitude","aliases"],"additionalProperties":false},"Community":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"community":{"type":"string"},"parent_area":{"anyOf":[{"type":"string"},{"type":"null"}]},"hierarchy_level":{"anyOf":[{"type":"string"},{"type":"null"}]},"location_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The same community as a place of the locations tree (GET /locations/{id}); null while it has none"}},"required":["id","community","parent_area","hierarchy_level","location_id"],"additionalProperties":false},"Location":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Stable place id. Area ids equal the `id` of `/v1/areas`."},"name":{"type":"string"},"name_ar":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The Arabic name, when we have one"},"level":{"type":"string","enum":["city","region","area","community","sub_community","cluster","building"]},"parent_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The place it sits directly in (the last breadcrumb entry); null for a city"},"breadcrumb":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"},"level":{"type":"string","enum":["city","region","area","community","sub_community","cluster","building"]}},"required":["id","name","level"],"additionalProperties":false},"description":"The places it sits in, root (the city) first; the place itself excluded"},"is_umbrella":{"type":"boolean","description":"A place too big to be one neighbourhood — every city and region, and large areas such as Dubai South"},"lat":{"anyOf":[{"type":"number"},{"type":"null"}]},"lng":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["id","name","name_ar","level","parent_id","breadcrumb","is_umbrella","lat","lng"],"additionalProperties":false},"LocationDetail":{"type":"object","properties":{"node":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Stable place id. Area ids equal the `id` of `/v1/areas`."},"name":{"type":"string"},"name_ar":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The Arabic name, when we have one"},"level":{"type":"string","enum":["city","region","area","community","sub_community","cluster","building"]},"parent_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The place it sits directly in (the last breadcrumb entry); null for a city"},"breadcrumb":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"},"level":{"type":"string","enum":["city","region","area","community","sub_community","cluster","building"]}},"required":["id","name","level"],"additionalProperties":false},"description":"The places it sits in, root (the city) first; the place itself excluded"},"is_umbrella":{"type":"boolean","description":"A place too big to be one neighbourhood — every city and region, and large areas such as Dubai South"},"lat":{"anyOf":[{"type":"number"},{"type":"null"}]},"lng":{"anyOf":[{"type":"number"},{"type":"null"}]},"depth":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"0 = a city"},"path":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"description":"Root → self ids"},"slug":{"type":"string"},"name_norm":{"type":"string","description":"The name in the resolver's normal form"},"name_core":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The name without a trailing “(…)”, normalised; null when it has none"},"kind":{"type":"string","description":"residential · other · zone (a DLD survey parcel) · school · nursery"},"is_place":{"type":"boolean","description":"False for schools and nurseries — points of interest, never a listing's place"},"active":{"type":"boolean","description":"False = retired or merged (see merged_into_id)"},"merged_into_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The place it was merged into — use that id instead"},"umbrella_computed":{"type":"boolean","description":"Umbrella by the spread of its places"},"umbrella_override":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"An admin's decision, when there is one (areas only)"},"umbrella_p90_km":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"90th-percentile distance of its places from its centre, km"},"umbrella_descendants":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"nbhd_top_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Its neighbourhood: the highest non-umbrella place on its path (null for an umbrella)"},"geocoded_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"geo_source":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"legacy · portal · registry · geocoder · manual"},"legacy_area_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Its id in `/v1/areas` (areas only; equals `id`)"},"legacy_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Whether `/v1/areas` still lists it"},"legacy_latitude":{"anyOf":[{"type":"number"},{"type":"null"}]},"legacy_longitude":{"anyOf":[{"type":"number"},{"type":"null"}]},"legacy_geocoded_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"legacy_geocode_source":{"anyOf":[{"type":"string"},{"type":"null"}]},"legacy_project_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Its id in the old project catalogue"},"legacy_community_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Its id in `/v1/communities`"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"aliases":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"lang":{"type":"string","description":"`en` or `ar`"},"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The alias row's own id"},"norm":{"type":"string","description":"The text in the resolver's normal form (what lookups compare)"},"kind":{"type":"string","description":"variant · abbreviation · former_name · official · marketing · legacy_area_alias · legacy_community_alias · legacy_project_alias · catalogue_name"},"origin":{"type":"string","description":"Where the alias came from (e.g. `bayut_title_ar`, `legacy:project_aliases:123`, `manual:…`)"},"legacy_table":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The legacy table the alias mirrors, if any"},"legacy_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Its row id in that legacy table"},"active":{"type":"boolean","description":"False = kept for the record, no longer read"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["text","lang","id","norm","kind","origin","legacy_table","legacy_id","active","created_at"],"additionalProperties":false},"description":"Every alias row filed under this place, inactive ones included"},"refs":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","enum":["bayut","dld_area","dld_master_project","dld_project","dld_building","legacy_area","legacy_community","legacy_project"]},"id":{"type":"string","description":"The place's id in that system"},"primary":{"type":"boolean","description":"The id that system itself uses for this place. A place can also answer to a secondary id (a duplicate that system once listed). Legacy ids are always primary."},"row_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The row's own id (null for a legacy id)"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The place's name in that system"},"name_ar":{"anyOf":[{"type":"string"},{"type":"null"}]},"parent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The id of its parent in that system"},"path":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Its path in that system, as that system writes it"},"lat":{"anyOf":[{"type":"number"},{"type":"null"}]},"lng":{"anyOf":[{"type":"number"},{"type":"null"}]},"first_seen_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_seen_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"gone_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When that system stopped listing it; null while it still does"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["source","id","primary","row_id","name","name_ar","parent_id","path","lat","lng","first_seen_at","last_seen_at","gone_at","created_at"],"additionalProperties":false},"description":"Every outside id filed under this place, then its legacy ids"}},"required":["id","name","name_ar","level","parent_id","breadcrumb","is_umbrella","lat","lng","depth","path","slug","name_norm","name_core","kind","is_place","active","merged_into_id","umbrella_computed","umbrella_override","umbrella_p90_km","umbrella_descendants","nbhd_top_id","geocoded_at","geo_source","legacy_area_id","legacy_active","legacy_latitude","legacy_longitude","legacy_geocoded_at","legacy_geocode_source","legacy_project_id","legacy_community_id","created_at","updated_at","aliases","refs"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Stable place id. Area ids equal the `id` of `/v1/areas`."},"name":{"type":"string"},"name_ar":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The Arabic name, when we have one"},"level":{"type":"string","enum":["city","region","area","community","sub_community","cluster","building"]},"parent_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The place it sits directly in (the last breadcrumb entry); null for a city"},"breadcrumb":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"},"level":{"type":"string","enum":["city","region","area","community","sub_community","cluster","building"]}},"required":["id","name","level"],"additionalProperties":false},"description":"The places it sits in, root (the city) first; the place itself excluded"},"is_umbrella":{"type":"boolean","description":"A place too big to be one neighbourhood — every city and region, and large areas such as Dubai South"},"lat":{"anyOf":[{"type":"number"},{"type":"null"}]},"lng":{"anyOf":[{"type":"number"},{"type":"null"}]},"aliases":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"lang":{"type":"string","description":"`en` or `ar`"}},"required":["text","lang"],"additionalProperties":false},"description":"Other texts iMatch reads as this place — see the Locations guide"}},"required":["id","name","name_ar","level","parent_id","breadcrumb","is_umbrella","lat","lng","aliases"],"additionalProperties":false}],"description":"Compact for every partner; every field with `locations_refs` (the full tree)"},"ancestors":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Stable place id. Area ids equal the `id` of `/v1/areas`."},"name":{"type":"string"},"name_ar":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The Arabic name, when we have one"},"level":{"type":"string","enum":["city","region","area","community","sub_community","cluster","building"]},"parent_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The place it sits directly in (the last breadcrumb entry); null for a city"},"breadcrumb":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"},"level":{"type":"string","enum":["city","region","area","community","sub_community","cluster","building"]}},"required":["id","name","level"],"additionalProperties":false},"description":"The places it sits in, root (the city) first; the place itself excluded"},"is_umbrella":{"type":"boolean","description":"A place too big to be one neighbourhood — every city and region, and large areas such as Dubai South"},"lat":{"anyOf":[{"type":"number"},{"type":"null"}]},"lng":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["id","name","name_ar","level","parent_id","breadcrumb","is_umbrella","lat","lng"],"additionalProperties":false},"description":"The places it sits in, root first"},"children":{"type":"object","properties":{"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Stable place id. Area ids equal the `id` of `/v1/areas`."},"name":{"type":"string"},"name_ar":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The Arabic name, when we have one"},"level":{"type":"string","enum":["city","region","area","community","sub_community","cluster","building"]},"parent_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The place it sits directly in (the last breadcrumb entry); null for a city"},"breadcrumb":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"},"level":{"type":"string","enum":["city","region","area","community","sub_community","cluster","building"]}},"required":["id","name","level"],"additionalProperties":false},"description":"The places it sits in, root (the city) first; the place itself excluded"},"is_umbrella":{"type":"boolean","description":"A place too big to be one neighbourhood — every city and region, and large areas such as Dubai South"},"lat":{"anyOf":[{"type":"number"},{"type":"null"}]},"lng":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["id","name","name_ar","level","parent_id","breadcrumb","is_umbrella","lat","lng"],"additionalProperties":false}},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Pass as `cursor` for the next page; null on the last page"},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Places directly inside, across all pages"}},"required":["items","next_cursor","total"],"additionalProperties":false,"description":"First page of the places directly inside, A–Z"}},"required":["node","ancestors","children"],"additionalProperties":false},"LocationFull":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Stable place id. Area ids equal the `id` of `/v1/areas`."},"name":{"type":"string"},"name_ar":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The Arabic name, when we have one"},"level":{"type":"string","enum":["city","region","area","community","sub_community","cluster","building"]},"parent_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The place it sits directly in (the last breadcrumb entry); null for a city"},"breadcrumb":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"},"level":{"type":"string","enum":["city","region","area","community","sub_community","cluster","building"]}},"required":["id","name","level"],"additionalProperties":false},"description":"The places it sits in, root (the city) first; the place itself excluded"},"is_umbrella":{"type":"boolean","description":"A place too big to be one neighbourhood — every city and region, and large areas such as Dubai South"},"lat":{"anyOf":[{"type":"number"},{"type":"null"}]},"lng":{"anyOf":[{"type":"number"},{"type":"null"}]},"depth":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"0 = a city"},"path":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"description":"Root → self ids"},"slug":{"type":"string"},"name_norm":{"type":"string","description":"The name in the resolver's normal form"},"name_core":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The name without a trailing “(…)”, normalised; null when it has none"},"kind":{"type":"string","description":"residential · other · zone (a DLD survey parcel) · school · nursery"},"is_place":{"type":"boolean","description":"False for schools and nurseries — points of interest, never a listing's place"},"active":{"type":"boolean","description":"False = retired or merged (see merged_into_id)"},"merged_into_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The place it was merged into — use that id instead"},"umbrella_computed":{"type":"boolean","description":"Umbrella by the spread of its places"},"umbrella_override":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"An admin's decision, when there is one (areas only)"},"umbrella_p90_km":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"90th-percentile distance of its places from its centre, km"},"umbrella_descendants":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"nbhd_top_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Its neighbourhood: the highest non-umbrella place on its path (null for an umbrella)"},"geocoded_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"geo_source":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"legacy · portal · registry · geocoder · manual"},"legacy_area_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Its id in `/v1/areas` (areas only; equals `id`)"},"legacy_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Whether `/v1/areas` still lists it"},"legacy_latitude":{"anyOf":[{"type":"number"},{"type":"null"}]},"legacy_longitude":{"anyOf":[{"type":"number"},{"type":"null"}]},"legacy_geocoded_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"legacy_geocode_source":{"anyOf":[{"type":"string"},{"type":"null"}]},"legacy_project_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Its id in the old project catalogue"},"legacy_community_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Its id in `/v1/communities`"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"aliases":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"lang":{"type":"string","description":"`en` or `ar`"},"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The alias row's own id"},"norm":{"type":"string","description":"The text in the resolver's normal form (what lookups compare)"},"kind":{"type":"string","description":"variant · abbreviation · former_name · official · marketing · legacy_area_alias · legacy_community_alias · legacy_project_alias · catalogue_name"},"origin":{"type":"string","description":"Where the alias came from (e.g. `bayut_title_ar`, `legacy:project_aliases:123`, `manual:…`)"},"legacy_table":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The legacy table the alias mirrors, if any"},"legacy_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Its row id in that legacy table"},"active":{"type":"boolean","description":"False = kept for the record, no longer read"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["text","lang","id","norm","kind","origin","legacy_table","legacy_id","active","created_at"],"additionalProperties":false},"description":"Every alias row filed under this place, inactive ones included"},"refs":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","enum":["bayut","dld_area","dld_master_project","dld_project","dld_building","legacy_area","legacy_community","legacy_project"]},"id":{"type":"string","description":"The place's id in that system"},"primary":{"type":"boolean","description":"The id that system itself uses for this place. A place can also answer to a secondary id (a duplicate that system once listed). Legacy ids are always primary."},"row_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The row's own id (null for a legacy id)"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The place's name in that system"},"name_ar":{"anyOf":[{"type":"string"},{"type":"null"}]},"parent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The id of its parent in that system"},"path":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Its path in that system, as that system writes it"},"lat":{"anyOf":[{"type":"number"},{"type":"null"}]},"lng":{"anyOf":[{"type":"number"},{"type":"null"}]},"first_seen_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_seen_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"gone_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When that system stopped listing it; null while it still does"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["source","id","primary","row_id","name","name_ar","parent_id","path","lat","lng","first_seen_at","last_seen_at","gone_at","created_at"],"additionalProperties":false},"description":"Every outside id filed under this place, then its legacy ids"}},"required":["id","name","name_ar","level","parent_id","breadcrumb","is_umbrella","lat","lng","depth","path","slug","name_norm","name_core","kind","is_place","active","merged_into_id","umbrella_computed","umbrella_override","umbrella_p90_km","umbrella_descendants","nbhd_top_id","geocoded_at","geo_source","legacy_area_id","legacy_active","legacy_latitude","legacy_longitude","legacy_geocoded_at","legacy_geocode_source","legacy_project_id","legacy_community_id","created_at","updated_at","aliases","refs"],"additionalProperties":false},"LocationExportPlace":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Stable place id. Area ids equal the `id` of `/v1/areas`."},"name":{"type":"string"},"name_ar":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The Arabic name, when we have one"},"level":{"type":"string","enum":["city","region","area","community","sub_community","cluster","building"]},"parent_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The place it sits directly in (the last breadcrumb entry); null for a city"},"breadcrumb":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"},"level":{"type":"string","enum":["city","region","area","community","sub_community","cluster","building"]}},"required":["id","name","level"],"additionalProperties":false},"description":"The places it sits in, root (the city) first; the place itself excluded"},"is_umbrella":{"type":"boolean","description":"A place too big to be one neighbourhood — every city and region, and large areas such as Dubai South"},"lat":{"anyOf":[{"type":"number"},{"type":"null"}]},"lng":{"anyOf":[{"type":"number"},{"type":"null"}]},"depth":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"0 = a city"},"path":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"description":"Root → self ids"},"slug":{"type":"string"},"name_norm":{"type":"string","description":"The name in the resolver's normal form"},"name_core":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The name without a trailing “(…)”, normalised; null when it has none"},"kind":{"type":"string","description":"residential · other · zone (a DLD survey parcel) · school · nursery"},"is_place":{"type":"boolean","description":"False for schools and nurseries — points of interest, never a listing's place"},"active":{"type":"boolean","description":"False = retired or merged (see merged_into_id)"},"merged_into_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The place it was merged into — use that id instead"},"umbrella_computed":{"type":"boolean","description":"Umbrella by the spread of its places"},"umbrella_override":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"An admin's decision, when there is one (areas only)"},"umbrella_p90_km":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"90th-percentile distance of its places from its centre, km"},"umbrella_descendants":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"nbhd_top_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Its neighbourhood: the highest non-umbrella place on its path (null for an umbrella)"},"geocoded_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"geo_source":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"legacy · portal · registry · geocoder · manual"},"legacy_area_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Its id in `/v1/areas` (areas only; equals `id`)"},"legacy_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Whether `/v1/areas` still lists it"},"legacy_latitude":{"anyOf":[{"type":"number"},{"type":"null"}]},"legacy_longitude":{"anyOf":[{"type":"number"},{"type":"null"}]},"legacy_geocoded_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"legacy_geocode_source":{"anyOf":[{"type":"string"},{"type":"null"}]},"legacy_project_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Its id in the old project catalogue"},"legacy_community_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Its id in `/v1/communities`"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"aliases":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"lang":{"type":"string","description":"`en` or `ar`"},"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The alias row's own id"},"norm":{"type":"string","description":"The text in the resolver's normal form (what lookups compare)"},"kind":{"type":"string","description":"variant · abbreviation · former_name · official · marketing · legacy_area_alias · legacy_community_alias · legacy_project_alias · catalogue_name"},"origin":{"type":"string","description":"Where the alias came from (e.g. `bayut_title_ar`, `legacy:project_aliases:123`, `manual:…`)"},"legacy_table":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The legacy table the alias mirrors, if any"},"legacy_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Its row id in that legacy table"},"active":{"type":"boolean","description":"False = kept for the record, no longer read"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["text","lang","id","norm","kind","origin","legacy_table","legacy_id","active","created_at"],"additionalProperties":false},"description":"Every alias row filed under this place, inactive ones included"},"refs":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","enum":["bayut","dld_area","dld_master_project","dld_project","dld_building","legacy_area","legacy_community","legacy_project"]},"id":{"type":"string","description":"The place's id in that system"},"primary":{"type":"boolean","description":"The id that system itself uses for this place. A place can also answer to a secondary id (a duplicate that system once listed). Legacy ids are always primary."},"row_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The row's own id (null for a legacy id)"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The place's name in that system"},"name_ar":{"anyOf":[{"type":"string"},{"type":"null"}]},"parent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The id of its parent in that system"},"path":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Its path in that system, as that system writes it"},"lat":{"anyOf":[{"type":"number"},{"type":"null"}]},"lng":{"anyOf":[{"type":"number"},{"type":"null"}]},"first_seen_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_seen_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"gone_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When that system stopped listing it; null while it still does"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["source","id","primary","row_id","name","name_ar","parent_id","path","lat","lng","first_seen_at","last_seen_at","gone_at","created_at"],"additionalProperties":false},"description":"Every outside id filed under this place, then its legacy ids"}},"required":["id","name","name_ar","level","parent_id","breadcrumb","is_umbrella","lat","lng","depth","path","slug","name_norm","name_core","kind","is_place","active","merged_into_id","umbrella_computed","umbrella_override","umbrella_p90_km","umbrella_descendants","nbhd_top_id","geocoded_at","geo_source","legacy_area_id","legacy_active","legacy_latitude","legacy_longitude","legacy_geocoded_at","legacy_geocode_source","legacy_project_id","legacy_community_id","created_at","updated_at","aliases","refs"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Stable place id. Area ids equal the `id` of `/v1/areas`."},"name":{"type":"string"},"name_ar":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The Arabic name, when we have one"},"level":{"type":"string","enum":["city","region","area","community","sub_community","cluster","building"]},"parent_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The place it sits directly in (the last breadcrumb entry); null for a city"},"breadcrumb":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"},"level":{"type":"string","enum":["city","region","area","community","sub_community","cluster","building"]}},"required":["id","name","level"],"additionalProperties":false},"description":"The places it sits in, root (the city) first; the place itself excluded"},"is_umbrella":{"type":"boolean","description":"A place too big to be one neighbourhood — every city and region, and large areas such as Dubai South"},"lat":{"anyOf":[{"type":"number"},{"type":"null"}]},"lng":{"anyOf":[{"type":"number"},{"type":"null"}]},"aliases":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"lang":{"type":"string","description":"`en` or `ar`"}},"required":["text","lang"],"additionalProperties":false},"description":"Other texts iMatch reads as this place — see the Locations guide"}},"required":["id","name","name_ar","level","parent_id","breadcrumb","is_umbrella","lat","lng","aliases"],"additionalProperties":false}]},"LocationRetired":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"An id that no longer answers as a place of its own"},"merged_into":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The live place it was merged into — re-point anything you stored to this id. Null when it left the tree with no successor."}},"required":["id","merged_into"],"additionalProperties":false},"LocationChange":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The place that changed"},"change":{"type":"string","enum":["created","updated","deleted"],"description":"`created` — new since you last looked. `updated` — the place, one of its aliases or outside ids, or a place above it (its breadcrumb) changed. `deleted` — no longer a live place: switched off, or merged (`merged_into_id`)."},"at":{"type":"string","description":"ISO 8601 with microseconds — the place's `updated_at`; the feed's order"},"merged_into_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The place it was merged into — re-point anything you stored to this id. Null unless merged."},"place":{"anyOf":[{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Stable place id. Area ids equal the `id` of `/v1/areas`."},"name":{"type":"string"},"name_ar":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The Arabic name, when we have one"},"level":{"type":"string","enum":["city","region","area","community","sub_community","cluster","building"]},"parent_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The place it sits directly in (the last breadcrumb entry); null for a city"},"breadcrumb":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"},"level":{"type":"string","enum":["city","region","area","community","sub_community","cluster","building"]}},"required":["id","name","level"],"additionalProperties":false},"description":"The places it sits in, root (the city) first; the place itself excluded"},"is_umbrella":{"type":"boolean","description":"A place too big to be one neighbourhood — every city and region, and large areas such as Dubai South"},"lat":{"anyOf":[{"type":"number"},{"type":"null"}]},"lng":{"anyOf":[{"type":"number"},{"type":"null"}]},"depth":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"0 = a city"},"path":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"description":"Root → self ids"},"slug":{"type":"string"},"name_norm":{"type":"string","description":"The name in the resolver's normal form"},"name_core":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The name without a trailing “(…)”, normalised; null when it has none"},"kind":{"type":"string","description":"residential · other · zone (a DLD survey parcel) · school · nursery"},"is_place":{"type":"boolean","description":"False for schools and nurseries — points of interest, never a listing's place"},"active":{"type":"boolean","description":"False = retired or merged (see merged_into_id)"},"merged_into_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The place it was merged into — use that id instead"},"umbrella_computed":{"type":"boolean","description":"Umbrella by the spread of its places"},"umbrella_override":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"An admin's decision, when there is one (areas only)"},"umbrella_p90_km":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"90th-percentile distance of its places from its centre, km"},"umbrella_descendants":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"nbhd_top_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Its neighbourhood: the highest non-umbrella place on its path (null for an umbrella)"},"geocoded_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"geo_source":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"legacy · portal · registry · geocoder · manual"},"legacy_area_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Its id in `/v1/areas` (areas only; equals `id`)"},"legacy_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Whether `/v1/areas` still lists it"},"legacy_latitude":{"anyOf":[{"type":"number"},{"type":"null"}]},"legacy_longitude":{"anyOf":[{"type":"number"},{"type":"null"}]},"legacy_geocoded_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"legacy_geocode_source":{"anyOf":[{"type":"string"},{"type":"null"}]},"legacy_project_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Its id in the old project catalogue"},"legacy_community_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Its id in `/v1/communities`"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"aliases":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"lang":{"type":"string","description":"`en` or `ar`"},"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The alias row's own id"},"norm":{"type":"string","description":"The text in the resolver's normal form (what lookups compare)"},"kind":{"type":"string","description":"variant · abbreviation · former_name · official · marketing · legacy_area_alias · legacy_community_alias · legacy_project_alias · catalogue_name"},"origin":{"type":"string","description":"Where the alias came from (e.g. `bayut_title_ar`, `legacy:project_aliases:123`, `manual:…`)"},"legacy_table":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The legacy table the alias mirrors, if any"},"legacy_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Its row id in that legacy table"},"active":{"type":"boolean","description":"False = kept for the record, no longer read"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["text","lang","id","norm","kind","origin","legacy_table","legacy_id","active","created_at"],"additionalProperties":false},"description":"Every alias row filed under this place, inactive ones included"},"refs":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","enum":["bayut","dld_area","dld_master_project","dld_project","dld_building","legacy_area","legacy_community","legacy_project"]},"id":{"type":"string","description":"The place's id in that system"},"primary":{"type":"boolean","description":"The id that system itself uses for this place. A place can also answer to a secondary id (a duplicate that system once listed). Legacy ids are always primary."},"row_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The row's own id (null for a legacy id)"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The place's name in that system"},"name_ar":{"anyOf":[{"type":"string"},{"type":"null"}]},"parent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The id of its parent in that system"},"path":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Its path in that system, as that system writes it"},"lat":{"anyOf":[{"type":"number"},{"type":"null"}]},"lng":{"anyOf":[{"type":"number"},{"type":"null"}]},"first_seen_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_seen_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"gone_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When that system stopped listing it; null while it still does"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["source","id","primary","row_id","name","name_ar","parent_id","path","lat","lng","first_seen_at","last_seen_at","gone_at","created_at"],"additionalProperties":false},"description":"Every outside id filed under this place, then its legacy ids"}},"required":["id","name","name_ar","level","parent_id","breadcrumb","is_umbrella","lat","lng","depth","path","slug","name_norm","name_core","kind","is_place","active","merged_into_id","umbrella_computed","umbrella_override","umbrella_p90_km","umbrella_descendants","nbhd_top_id","geocoded_at","geo_source","legacy_area_id","legacy_active","legacy_latitude","legacy_longitude","legacy_geocoded_at","legacy_geocode_source","legacy_project_id","legacy_community_id","created_at","updated_at","aliases","refs"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Stable place id. Area ids equal the `id` of `/v1/areas`."},"name":{"type":"string"},"name_ar":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The Arabic name, when we have one"},"level":{"type":"string","enum":["city","region","area","community","sub_community","cluster","building"]},"parent_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The place it sits directly in (the last breadcrumb entry); null for a city"},"breadcrumb":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"},"level":{"type":"string","enum":["city","region","area","community","sub_community","cluster","building"]}},"required":["id","name","level"],"additionalProperties":false},"description":"The places it sits in, root (the city) first; the place itself excluded"},"is_umbrella":{"type":"boolean","description":"A place too big to be one neighbourhood — every city and region, and large areas such as Dubai South"},"lat":{"anyOf":[{"type":"number"},{"type":"null"}]},"lng":{"anyOf":[{"type":"number"},{"type":"null"}]},"aliases":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"lang":{"type":"string","description":"`en` or `ar`"}},"required":["text","lang"],"additionalProperties":false},"description":"Other texts iMatch reads as this place — see the Locations guide"}},"required":["id","name","name_ar","level","parent_id","breadcrumb","is_umbrella","lat","lng","aliases"],"additionalProperties":false}]},{"type":"null"}],"description":"The place as the export shows it — every field with `locations_refs`, the compact place otherwise. Null (compact scope) when it is no longer a live place."}},"required":["id","change","at","merged_into_id","place"],"additionalProperties":false},"LocationUpdatedEventData":{"type":"object","properties":{"scope":{"type":"string","enum":["compact","full"],"description":"Your tree scope — the shape `place` is in"},"locations":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The place that changed"},"change":{"type":"string","enum":["created","updated","deleted"],"description":"`created` — new since you last looked. `updated` — the place, one of its aliases or outside ids, or a place above it (its breadcrumb) changed. `deleted` — no longer a live place: switched off, or merged (`merged_into_id`)."},"at":{"type":"string","description":"ISO 8601 with microseconds — the place's `updated_at`; the feed's order"},"merged_into_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The place it was merged into — re-point anything you stored to this id. Null unless merged."},"place":{"anyOf":[{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Stable place id. Area ids equal the `id` of `/v1/areas`."},"name":{"type":"string"},"name_ar":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The Arabic name, when we have one"},"level":{"type":"string","enum":["city","region","area","community","sub_community","cluster","building"]},"parent_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The place it sits directly in (the last breadcrumb entry); null for a city"},"breadcrumb":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"},"level":{"type":"string","enum":["city","region","area","community","sub_community","cluster","building"]}},"required":["id","name","level"],"additionalProperties":false},"description":"The places it sits in, root (the city) first; the place itself excluded"},"is_umbrella":{"type":"boolean","description":"A place too big to be one neighbourhood — every city and region, and large areas such as Dubai South"},"lat":{"anyOf":[{"type":"number"},{"type":"null"}]},"lng":{"anyOf":[{"type":"number"},{"type":"null"}]},"depth":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"0 = a city"},"path":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"description":"Root → self ids"},"slug":{"type":"string"},"name_norm":{"type":"string","description":"The name in the resolver's normal form"},"name_core":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The name without a trailing “(…)”, normalised; null when it has none"},"kind":{"type":"string","description":"residential · other · zone (a DLD survey parcel) · school · nursery"},"is_place":{"type":"boolean","description":"False for schools and nurseries — points of interest, never a listing's place"},"active":{"type":"boolean","description":"False = retired or merged (see merged_into_id)"},"merged_into_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The place it was merged into — use that id instead"},"umbrella_computed":{"type":"boolean","description":"Umbrella by the spread of its places"},"umbrella_override":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"An admin's decision, when there is one (areas only)"},"umbrella_p90_km":{"anyOf":[{"type":"number"},{"type":"null"}],"description":"90th-percentile distance of its places from its centre, km"},"umbrella_descendants":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"nbhd_top_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Its neighbourhood: the highest non-umbrella place on its path (null for an umbrella)"},"geocoded_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"geo_source":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"legacy · portal · registry · geocoder · manual"},"legacy_area_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Its id in `/v1/areas` (areas only; equals `id`)"},"legacy_active":{"anyOf":[{"type":"boolean"},{"type":"null"}],"description":"Whether `/v1/areas` still lists it"},"legacy_latitude":{"anyOf":[{"type":"number"},{"type":"null"}]},"legacy_longitude":{"anyOf":[{"type":"number"},{"type":"null"}]},"legacy_geocoded_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"legacy_geocode_source":{"anyOf":[{"type":"string"},{"type":"null"}]},"legacy_project_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Its id in the old project catalogue"},"legacy_community_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Its id in `/v1/communities`"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"aliases":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"lang":{"type":"string","description":"`en` or `ar`"},"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The alias row's own id"},"norm":{"type":"string","description":"The text in the resolver's normal form (what lookups compare)"},"kind":{"type":"string","description":"variant · abbreviation · former_name · official · marketing · legacy_area_alias · legacy_community_alias · legacy_project_alias · catalogue_name"},"origin":{"type":"string","description":"Where the alias came from (e.g. `bayut_title_ar`, `legacy:project_aliases:123`, `manual:…`)"},"legacy_table":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The legacy table the alias mirrors, if any"},"legacy_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Its row id in that legacy table"},"active":{"type":"boolean","description":"False = kept for the record, no longer read"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["text","lang","id","norm","kind","origin","legacy_table","legacy_id","active","created_at"],"additionalProperties":false},"description":"Every alias row filed under this place, inactive ones included"},"refs":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string","enum":["bayut","dld_area","dld_master_project","dld_project","dld_building","legacy_area","legacy_community","legacy_project"]},"id":{"type":"string","description":"The place's id in that system"},"primary":{"type":"boolean","description":"The id that system itself uses for this place. A place can also answer to a secondary id (a duplicate that system once listed). Legacy ids are always primary."},"row_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The row's own id (null for a legacy id)"},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The place's name in that system"},"name_ar":{"anyOf":[{"type":"string"},{"type":"null"}]},"parent_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The id of its parent in that system"},"path":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Its path in that system, as that system writes it"},"lat":{"anyOf":[{"type":"number"},{"type":"null"}]},"lng":{"anyOf":[{"type":"number"},{"type":"null"}]},"first_seen_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"last_seen_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"gone_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When that system stopped listing it; null while it still does"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["source","id","primary","row_id","name","name_ar","parent_id","path","lat","lng","first_seen_at","last_seen_at","gone_at","created_at"],"additionalProperties":false},"description":"Every outside id filed under this place, then its legacy ids"}},"required":["id","name","name_ar","level","parent_id","breadcrumb","is_umbrella","lat","lng","depth","path","slug","name_norm","name_core","kind","is_place","active","merged_into_id","umbrella_computed","umbrella_override","umbrella_p90_km","umbrella_descendants","nbhd_top_id","geocoded_at","geo_source","legacy_area_id","legacy_active","legacy_latitude","legacy_longitude","legacy_geocoded_at","legacy_geocode_source","legacy_project_id","legacy_community_id","created_at","updated_at","aliases","refs"],"additionalProperties":false},{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Stable place id. Area ids equal the `id` of `/v1/areas`."},"name":{"type":"string"},"name_ar":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The Arabic name, when we have one"},"level":{"type":"string","enum":["city","region","area","community","sub_community","cluster","building"]},"parent_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The place it sits directly in (the last breadcrumb entry); null for a city"},"breadcrumb":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"},"level":{"type":"string","enum":["city","region","area","community","sub_community","cluster","building"]}},"required":["id","name","level"],"additionalProperties":false},"description":"The places it sits in, root (the city) first; the place itself excluded"},"is_umbrella":{"type":"boolean","description":"A place too big to be one neighbourhood — every city and region, and large areas such as Dubai South"},"lat":{"anyOf":[{"type":"number"},{"type":"null"}]},"lng":{"anyOf":[{"type":"number"},{"type":"null"}]},"aliases":{"type":"array","items":{"type":"object","properties":{"text":{"type":"string"},"lang":{"type":"string","description":"`en` or `ar`"}},"required":["text","lang"],"additionalProperties":false},"description":"Other texts iMatch reads as this place — see the Locations guide"}},"required":["id","name","name_ar","level","parent_id","breadcrumb","is_umbrella","lat","lng","aliases"],"additionalProperties":false}]},{"type":"null"}],"description":"The place as the export shows it — every field with `locations_refs`, the compact place otherwise. Null (compact scope) when it is no longer a live place."}},"required":["id","change","at","merged_into_id","place"],"additionalProperties":false},"description":"The places that changed, each once, oldest change first — at most 100 per delivery"},"cursor":{"type":"string","description":"The `/locations/changes` cursor right after the last place in this delivery — resume the feed from here if you ever need to"}},"required":["scope","locations","cursor"],"additionalProperties":false},"LifecycleReason":{"type":"string","enum":["partner","expiry","imatch"],"description":"`partner` — your own API call. `expiry` — iMatch's daily expiry. `imatch` — someone or something on iMatch's side."},"LifecycleActor":{"type":"string","description":"Your partner slug (reason partner), or one of: `system:auto-unlist`, `imatch:admin`, `imatch:user`, `imatch:system`. Never a person's name, id, phone or email."},"LocationResolve":{"type":"object","properties":{"status":{"type":"string","enum":["resolved","ambiguous","unresolved"],"description":"`resolved` — one place, no guess. `ambiguous` — the text fits several places: `place` is the one iMatch would choose (null when it would not choose). `unresolved` — no place."},"place":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Stable place id. Area ids equal the `id` of `/v1/areas`."},"name":{"type":"string"},"name_ar":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The Arabic name, when we have one"},"level":{"type":"string","enum":["city","region","area","community","sub_community","cluster","building"]},"parent_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The place it sits directly in (the last breadcrumb entry); null for a city"},"breadcrumb":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"},"level":{"type":"string","enum":["city","region","area","community","sub_community","cluster","building"]}},"required":["id","name","level"],"additionalProperties":false},"description":"The places it sits in, root (the city) first; the place itself excluded"},"is_umbrella":{"type":"boolean","description":"A place too big to be one neighbourhood — every city and region, and large areas such as Dubai South"},"lat":{"anyOf":[{"type":"number"},{"type":"null"}]},"lng":{"anyOf":[{"type":"number"},{"type":"null"}]}},"required":["id","name","name_ar","level","parent_id","breadcrumb","is_umbrella","lat","lng"],"additionalProperties":false},{"type":"null"}],"description":"Where a listing with this text is placed; null when it would not be placed"},"candidates":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many places the text could mean (more than 1 = ambiguous)"},"conflicting_fields":{"type":"array","items":{"type":"string","enum":["area","community","project"]},"description":"Fields that name a place somewhere else than `place` — usually a text worth correcting"}},"required":["status","place","candidates","conflicting_fields"],"additionalProperties":false},"Match":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"score":{"anyOf":[{"type":"number"},{"type":"null"}]},"reason":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string"},"kind":{"type":"string","enum":["exact","nearby"],"description":"`exact`, or `nearby` — the right area but not the exact place (another building in the same community, or a community inside the area the buyer named). Nearby matches are only returned with `include=nearby` and only pushed with the `matches_nearby` feature; show them apart from exact matches, never mixed in."},"is_nearby":{"type":"boolean","description":"The same fact as `kind`, as a boolean: true exactly when kind is `nearby`."},"mine":{"type":"string","enum":["listing","inquiry","both"]},"listing":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"reference_no":{"anyOf":[{"type":"string"},{"type":"null"}]},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Your own id — only on rows you created"},"purpose":{"anyOf":[{"type":"string"},{"type":"null"}]},"property_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"category":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Normal | Distress (Distress only visible with distress_read)"},"location_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The place of the locations tree this listing is filed under (GET /locations/{id}); null while it is not placed"},"location":{"description":"That place, named, with the places it sits in — present on every API read and webhook payload","anyOf":[{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"},"level":{"type":"string","enum":["city","region","area","community","sub_community","cluster","building"]},"breadcrumb":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"name":{"type":"string"},"level":{"type":"string","enum":["city","region","area","community","sub_community","cluster","building"]}},"required":["id","name","level"],"additionalProperties":false}},"refs":{"description":"With `locations_refs` only: the place's PRIMARY outside ids (its Bayut id, DLD ids, legacy ids)","type":"array","items":{"type":"object","properties":{"source":{"type":"string","enum":["bayut","dld_area","dld_master_project","dld_project","dld_building","legacy_area","legacy_community","legacy_project"]},"id":{"type":"string","description":"The place's id in that system"},"primary":{"type":"boolean","description":"The id that system itself uses for this place. A place can also answer to a secondary id (a duplicate that system once listed). Legacy ids are always primary."}},"required":["source","id","primary"],"additionalProperties":false}}},"required":["id","name","level","breadcrumb"],"additionalProperties":false},{"type":"null"}]},"area":{"anyOf":[{"type":"string"},{"type":"null"}]},"community":{"anyOf":[{"type":"string"},{"type":"null"}]},"project":{"anyOf":[{"type":"string"},{"type":"null"}]},"developer":{"anyOf":[{"type":"string"},{"type":"null"}]},"floor":{"anyOf":[{"type":"string"},{"type":"null"}]},"bedrooms":{"anyOf":[{"type":"string"},{"type":"null"}]},"bathrooms":{"anyOf":[{"type":"string"},{"type":"null"}]},"bua_sqft":{"anyOf":[{"type":"number"},{"type":"null"}]},"plot_sqft":{"anyOf":[{"type":"number"},{"type":"null"}]},"view":{"anyOf":[{"type":"string"},{"type":"null"}]},"furnished":{"anyOf":[{"type":"string"},{"type":"null"}]},"completion_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"handover_date":{"anyOf":[{"type":"string"},{"type":"null"}]},"status":{"anyOf":[{"type":"string"},{"type":"null"}]},"live_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"vacancy":{"anyOf":[{"type":"string"},{"type":"null"}]},"selling_price":{"anyOf":[{"type":"number"},{"type":"null"}]},"rent_price":{"anyOf":[{"type":"number"},{"type":"null"}]},"price_per_sqft":{"anyOf":[{"type":"number"},{"type":"null"}]},"service_charges":{"anyOf":[{"type":"number"},{"type":"null"}]},"roi_percent":{"anyOf":[{"type":"number"},{"type":"null"}]},"rental_income":{"anyOf":[{"type":"number"},{"type":"null"}]},"currency":{"anyOf":[{"type":"string"},{"type":"null"}]},"payment_plan":{"anyOf":[{"type":"string"},{"type":"null"}]},"paid_percent":{"anyOf":[{"type":"string"},{"type":"null"}]},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"ai_summary":{"anyOf":[{"type":"string"},{"type":"null"}]},"extra_details":{"anyOf":[{"type":"string"},{"type":"null"}]},"extra_features":{"anyOf":[{"type":"string"},{"type":"null"}]},"permit_number":{"anyOf":[{"type":"string"},{"type":"null"}]},"date_listed":{"anyOf":[{"type":"string"},{"type":"null"}]},"expires_after":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"anyOf":[{"type":"string"},{"type":"null"}]},"photos":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Positive = a photo on this listing. Negative = a project photo iMatch added; it has no id of its own and cannot be deleted."},"kind":{"type":"string","enum":["photo","floor_plan","master_plan","project"],"description":"photo | floor_plan | master_plan = this listing's own media. project = a photo of the BUILDING or development the listing is in, from the iMatch project catalogue — NOT a photo of this unit."},"url":{"type":"string"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The url you sent when this photo was attached (null for base64, for project photos, and for any photo attached before 2026-09-26 — Connect did not keep it until then). Lets you check what iMatch holds without re-sending."},"position":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"0-based place of this photo among the listing's OWN photos, in display order. null for project photos."}},"required":["id","kind","url","source_url","position"],"additionalProperties":false},"description":"This listing's own images first, always. If it has none and we could match its `project` to our catalogue, the project's photos are appended with kind=\"project\" — pictures of the building, not of this unit."},"project_id":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"The iMatch project this listing was matched to, or null if we could not match one. Read it with GET /projects/{id}."},"project_photo_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The matched project's main photo — the BUILDING or development, not this unit. Present whether or not the listing has its own photos, so you can label it honestly. Null when no project matched or it has no photo."},"agent":{"type":"object","properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"brokerage":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"description":"Only with include=contact","anyOf":[{"type":"string"},{"type":"null"}]},"contact_withheld":{"description":"Present instead of a phone when this row's contact is not available through the API (code: contact_not_available_for_source). No reveal is charged.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]}},"required":["name","brokerage"],"additionalProperties":false},"url":{"type":"string","description":"The public page for this listing (viewable without an iMatch login) — the link to show in your CRM"},"distress_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"original_price":{"anyOf":[{"type":"number"},{"type":"null"}]},"market_price":{"anyOf":[{"type":"number"},{"type":"null"}]},"op_plus_dld":{"anyOf":[{"type":"number"},{"type":"null"}]},"discount_amount":{"anyOf":[{"type":"number"},{"type":"null"}]},"discount_percent":{"anyOf":[{"type":"number"},{"type":"null"}]},"seller_urgency":{"anyOf":[{"type":"string"},{"type":"null"}]},"total_on_transfer":{"anyOf":[{"type":"number"},{"type":"null"}]},"already_paid":{"anyOf":[{"type":"number"},{"type":"null"}]},"premium":{"anyOf":[{"type":"number"},{"type":"null"}]},"dld_fee":{"anyOf":[{"type":"number"},{"type":"null"}]},"commission":{"anyOf":[{"type":"number"},{"type":"null"}]},"pending_payment":{"anyOf":[{"type":"number"},{"type":"null"}]},"payment_notes":{"anyOf":[{"type":"string"},{"type":"null"}]}},"required":["id","reference_no","external_id","purpose","property_type","category","location_id","area","community","project","developer","floor","bedrooms","bathrooms","bua_sqft","plot_sqft","view","furnished","completion_status","handover_date","status","live_status","vacancy","selling_price","rent_price","price_per_sqft","service_charges","roi_percent","rental_income","currency","payment_plan","paid_percent","description","ai_summary","extra_details","extra_features","permit_number","date_listed","expires_after","created_at","updated_at","source","photos","project_id","project_photo_url","agent","url"],"additionalProperties":false},{"type":"null"}]},"inquiry":{"anyOf":[{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"reference_no":{"anyOf":[{"type":"string"},{"type":"null"}]},"external_id":{"anyOf":[{"type":"string"},{"type":"null"}]},"purpose":{"anyOf":[{"type":"string"},{"type":"null"}]},"location_wanted":{"anyOf":[{"type":"string"},{"type":"null"}]},"preferred_communities":{"anyOf":[{"type":"string"},{"type":"null"}]},"project_wanted":{"anyOf":[{"type":"string"},{"type":"null"}]},"developer_wanted":{"anyOf":[{"type":"string"},{"type":"null"}]},"property_type_wanted":{"anyOf":[{"type":"string"},{"type":"null"}]},"bedrooms_wanted":{"anyOf":[{"type":"string"},{"type":"null"}]},"bathrooms_wanted":{"anyOf":[{"type":"string"},{"type":"null"}]},"min_size_sqft":{"anyOf":[{"type":"number"},{"type":"null"}]},"max_size_sqft":{"anyOf":[{"type":"number"},{"type":"null"}]},"budget_min":{"anyOf":[{"type":"number"},{"type":"null"}]},"budget_max":{"anyOf":[{"type":"number"},{"type":"null"}]},"currency":{"anyOf":[{"type":"string"},{"type":"null"}]},"preferred_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"handover_preference":{"anyOf":[{"type":"string"},{"type":"null"}]},"preferred_type":{"anyOf":[{"type":"string"},{"type":"null"}]},"furnished_preference":{"anyOf":[{"type":"string"},{"type":"null"}]},"view_preference":{"anyOf":[{"type":"string"},{"type":"null"}]},"floor_preference":{"anyOf":[{"type":"string"},{"type":"null"}]},"vacancy_preference":{"anyOf":[{"type":"string"},{"type":"null"}]},"payment_plan_preference":{"anyOf":[{"type":"string"},{"type":"null"}]},"special_requirements":{"anyOf":[{"type":"string"},{"type":"null"}]},"ai_summary":{"anyOf":[{"type":"string"},{"type":"null"}]},"live_status":{"anyOf":[{"type":"string"},{"type":"null"}]},"date_received":{"anyOf":[{"type":"string"},{"type":"null"}]},"expires_after":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"source":{"anyOf":[{"type":"string"},{"type":"null"}]},"agent":{"type":"object","properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}]},"brokerage":{"anyOf":[{"type":"string"},{"type":"null"}]},"phone":{"description":"Only with include=contact","anyOf":[{"type":"string"},{"type":"null"}]},"contact_withheld":{"description":"Present instead of a phone when this row's contact is not available through the API (code: contact_not_available_for_source). No reveal is charged.","anyOf":[{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"}},"required":["code","message"],"additionalProperties":false},{"type":"null"}]}},"required":["name","brokerage"],"additionalProperties":false}},"required":["id","reference_no","external_id","purpose","location_wanted","preferred_communities","project_wanted","developer_wanted","property_type_wanted","bedrooms_wanted","bathrooms_wanted","min_size_sqft","max_size_sqft","budget_min","budget_max","currency","preferred_status","handover_preference","preferred_type","furnished_preference","view_preference","floor_preference","vacancy_preference","payment_plan_preference","special_requirements","ai_summary","live_status","date_received","expires_after","created_at","updated_at","source","agent"],"additionalProperties":false},{"type":"null"}]}},"required":["id","score","reason","status","created_at","kind","is_nearby","mine","listing","inquiry"],"additionalProperties":false},"AgentLink":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"The link id — pass it as `?as_agent=` to act for this person. Not a credential: authority is still your API key."},"external_user_id":{"type":"string","description":"Your own id for the CRM user"},"status":{"type":"string","enum":["pending","active","revoked","expired"]},"display_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The name YOU supplied when starting the link"},"scopes":{"type":"array","items":{"type":"string"}},"mode":{"type":"string","enum":["live","test"]},"connected_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"When the agent pressed Connect"},"last_used_at":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Last call made through this link"},"revoked_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"revoked_by":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"agent | partner | brokerage | platform | deactivation"},"created_at":{"type":"string"}},"required":["id","external_user_id","status","display_name","scopes","mode","connected_at","last_used_at","revoked_at","revoked_by","created_at"],"additionalProperties":false},"AgentLinkStart":{"type":"object","properties":{"link_id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Store this against the CRM user now — it is the id the link will carry."},"authorize_url":{"type":"string","description":"Send the agent's BROWSER here. Single use, half an hour. The token appears in no other response — do not store it."},"expires_at":{"type":"string","description":"When the authorize_url stops working"}},"required":["link_id","authorize_url","expires_at"],"additionalProperties":false},"Photo":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Positive = a photo on this listing. Negative = a project photo iMatch added; it has no id of its own and cannot be deleted."},"kind":{"type":"string","enum":["photo","floor_plan","master_plan","project"],"description":"photo | floor_plan | master_plan = this listing's own media. project = a photo of the BUILDING or development the listing is in, from the iMatch project catalogue — NOT a photo of this unit."},"url":{"type":"string"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The url you sent when this photo was attached (null for base64, for project photos, and for any photo attached before 2026-09-26 — Connect did not keep it until then). Lets you check what iMatch holds without re-sending."},"position":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"0-based place of this photo among the listing's OWN photos, in display order. null for project photos."}},"required":["id","kind","url","source_url","position"],"additionalProperties":false},"ChangeRow":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"external_id":{"description":"Your own id on rows you created; absent for projects and locations","anyOf":[{"type":"string"},{"type":"null"}]},"change":{"type":"string","enum":["created","updated","unlisted","sold","deleted"]},"at":{"type":"string","description":"ISO 8601 with microseconds — the row's updated_at"},"merged_into_id":{"description":"Locations only: the place a merged place now lives on (with `change: deleted`); null otherwise","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["id","change","at"],"additionalProperties":false},"ChangesData":{"type":"object","properties":{"listings":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"external_id":{"description":"Your own id on rows you created; absent for projects and locations","anyOf":[{"type":"string"},{"type":"null"}]},"change":{"type":"string","enum":["created","updated","unlisted","sold","deleted"]},"at":{"type":"string","description":"ISO 8601 with microseconds — the row's updated_at"},"merged_into_id":{"description":"Locations only: the place a merged place now lives on (with `change: deleted`); null otherwise","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["id","change","at"],"additionalProperties":false}},"inquiries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"external_id":{"description":"Your own id on rows you created; absent for projects and locations","anyOf":[{"type":"string"},{"type":"null"}]},"change":{"type":"string","enum":["created","updated","unlisted","sold","deleted"]},"at":{"type":"string","description":"ISO 8601 with microseconds — the row's updated_at"},"merged_into_id":{"description":"Locations only: the place a merged place now lives on (with `change: deleted`); null otherwise","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["id","change","at"],"additionalProperties":false}},"projects":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"external_id":{"description":"Your own id on rows you created; absent for projects and locations","anyOf":[{"type":"string"},{"type":"null"}]},"change":{"type":"string","enum":["created","updated","unlisted","sold","deleted"]},"at":{"type":"string","description":"ISO 8601 with microseconds — the row's updated_at"},"merged_into_id":{"description":"Locations only: the place a merged place now lives on (with `change: deleted`); null otherwise","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["id","change","at"],"additionalProperties":false}},"locations":{"description":"Only when you asked for `types=locations`","type":"array","items":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"external_id":{"description":"Your own id on rows you created; absent for projects and locations","anyOf":[{"type":"string"},{"type":"null"}]},"change":{"type":"string","enum":["created","updated","unlisted","sold","deleted"]},"at":{"type":"string","description":"ISO 8601 with microseconds — the row's updated_at"},"merged_into_id":{"description":"Locations only: the place a merged place now lives on (with `change: deleted`); null otherwise","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["id","change","at"],"additionalProperties":false}}},"additionalProperties":false},"Webhook":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"description":{"anyOf":[{"type":"string"},{"type":"null"}]},"active":{"type":"boolean"},"failure_count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Consecutive failed deliveries; 50 switches the webhook off"},"last_delivered_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"mode":{"type":"string","enum":["live","test"],"description":"The mode of the key that registered it. A test webhook only ever receives synthetic events and pings."},"secret":{"description":"ONLY in the response that created or rotated it. Store it; it is never shown again.","type":"string"}},"required":["id","url","events","description","active","failure_count","last_delivered_at","created_at","updated_at","mode"],"additionalProperties":false},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"webhook_id":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"event":{"type":"string"},"status":{"type":"string","enum":["pending","in_flight","delivered","failed"]},"attempts":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"last_error":{"anyOf":[{"type":"string"},{"type":"null"}]},"response_status":{"anyOf":[{"type":"number"},{"type":"null"}]},"response_ms":{"anyOf":[{"type":"number"},{"type":"null"}]},"next_attempt_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"delivered_at":{"anyOf":[{"type":"string"},{"type":"null"}]},"created_at":{"type":"string"},"mode":{"type":"string","enum":["live","test"],"description":"live = a real event; test = a synthetic event or a ping to a test webhook"},"payload":{"description":"The envelope as sent: { id, event, created_at, partner, data }. Detail endpoint only."}},"required":["id","webhook_id","event","status","attempts","last_error","response_status","response_ms","next_attempt_at","delivered_at","created_at","mode"],"additionalProperties":false},"EmbedSession":{"type":"object","properties":{"token":{"type":"string","description":"Short-lived embed token. Hand it to the browser; never the API key."},"expires_at":{"type":"string"},"embed_base":{"type":"string","description":"Prefix of the embed pages: `<embed_base>/offer?token=…`"},"tools":{"type":"array","items":{"type":"string","enum":["offer","poster","copilot","listings","projects","matches"]}}},"required":["token","expires_at","embed_base","tools"],"additionalProperties":false},"SandboxEvent":{"type":"object","properties":{"event":{"type":"string","enum":["match.created","listing.created","listing.updated","listing.unlisted","listing.sold","inquiry.created","inquiry.updated","inquiry.unlisted","distress.created","location.updated"]},"delivery_ids":{"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"description":"One per subscribed test webhook; empty when none is subscribed"},"enqueued":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many were handed to the delivery worker right away"},"data":{"description":"The `data` half of the envelope that was queued — what your endpoint will receive"}},"required":["event","delivery_ids","enqueued","data"],"additionalProperties":false},"CopilotChat":{"type":"object","properties":{"conversation_id":{"type":"string"},"reply":{"type":"string","description":"Plain text (no markdown)"},"actions":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["listing","inquiry","project","match"]},"ref":{"type":"string","description":"reference_no, project name, or id"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"REST URL of the record when it has one"},"tool":{"type":"string","description":"The Copilot tool that surfaced it"}},"required":["type","ref","url","tool"],"additionalProperties":false},"description":"Records the answer is about — link them in your UI"},"usage":{"type":"object","properties":{"tool_calls":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"tools":{"type":"array","items":{"type":"string"}},"history_turns":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Prior turns replayed to the model"},"model":{"anyOf":[{"type":"string"},{"type":"null"}]},"duration_ms":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["tool_calls","tools","history_turns","model","duration_ms"],"additionalProperties":false}},"required":["conversation_id","reply","actions","usage"],"additionalProperties":false},"CopilotAction":{"type":"object","properties":{"type":{"type":"string","enum":["listing","inquiry","project","match"]},"ref":{"type":"string","description":"reference_no, project name, or id"},"url":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"REST URL of the record when it has one"},"tool":{"type":"string","description":"The Copilot tool that surfaced it"}},"required":["type","ref","url","tool"],"additionalProperties":false},"WebhookEvent":{"type":"string","enum":["ping","match.created","listing.created","listing.updated","listing.unlisted","listing.sold","inquiry.created","inquiry.updated","inquiry.unlisted","distress.created","agent_link.connected","agent_link.revoked","location.updated","*"],"description":"Subscribable event names; `*` = all."},"WebhookEnvelope":{"type":"object","description":"The body of every delivery. `id` is the delivery id — use it as your idempotency key.","required":["id","event","created_at","partner","data"],"properties":{"id":{"type":"string"},"event":{"type":"string","enum":["ping","match.created","listing.created","listing.updated","listing.unlisted","listing.sold","inquiry.created","inquiry.updated","inquiry.unlisted","distress.created","agent_link.connected","agent_link.revoked","location.updated"]},"created_at":{"type":"string","format":"date-time"},"partner":{"type":"string","description":"Your partner slug"},"data":{"type":"object","description":"Per event: `{ listing, reason, actor }` / `{ inquiry, reason, actor }` for the lifecycle events of your own rows (`reason`: partner | expiry | imatch — see LifecycleReason / LifecycleActor), `{ listing }` for distress.created, `{ match, mine }`, `{ scope, locations, cursor }` for location.updated (LocationUpdatedEventData), `{ webhook_id }` for ping. Never a contact."}}},"FeatureKey":{"type":"string","enum":["listings_read","projects_read","units_read","inquiries_read","distress_read","areas_read","locations_refs","matches_read","listings_write","inquiries_write","photos_write","photos_replace","tools_embed","copilot","webhooks","matches_nearby"]}}}}