REST API

De REST API

Uw systemen lezen de catalogus van Realton en uw CRM, en schrijven klanten, notities, taken en dealfases weg, namens degene die de sleutel heeft gemaakt.

Agency-abonnement

Snel aan de slag

In Realton opent een eigenaar of beheerder Instellingen › API en MCP, vinkt REST API aan en kiest Sleutel maken. Kopieer hem meteen: hij wordt maar één keer getoond.
Bewaar hem op uw server, in een omgevingsvariabele:
```
export REALTON_API_KEY="rtk_live_…"
```

Doe uw eerste aanroep:

curl "https://realton.ai/api/v1/projects?place=Dubai&beds=2&limit=5" \
  -H "Authorization: Bearer $REALTON_API_KEY"

Bouwen met een AI

De meeste integraties worden tegenwoordig door een AI geschreven. Geef hem deze twee adressen en de taak in een paar woorden; de rest leest hij zelf.

De briefing /docs/api.mdOpenAPI 3.1 /docs/openapi.json

Een prompt om te kopiëren, met de haakjes ingevuld:

Ik wil [mijn website / mijn CRM / mijn systeem] koppelen aan de REST API van Realton.
Lees eerst de briefing: https://realton.ai/docs/api.md
Het volledige OpenAPI-document: https://realton.ai/docs/openapi.json
Mijn stack: [bijvoorbeeld Next.js op Vercel].
Wat ik wil: [bijvoorbeeld de projecten van Realton in Dubai op mijn site tonen, één keer per dag vernieuwd].
De API-sleutel staat in de omgevingsvariabele REALTON_API_KEY. Vraag mij nooit om de sleutel en zet hem nooit in de code.

Plak de sleutel nooit in een chat. Stel REALTON_API_KEY zelf in op de server en geef de AI alleen de naam ervan.

De regels

De sleutel

Elke aanroep stuurt de sleutel mee in de header Authorization. Een sleutel geeft alleen toegang tot de REST API als REST API was aangevinkt toen hij werd gemaakt, en alleen zolang de werkruimte het Agency-abonnement heeft.

Authorization: Bearer rtk_live_…

Namens wie een aanroep handelt

Een aanroep handelt namens het lid dat de sleutel heeft gemaakt, met wat dat lid mag zien: een makelaar de eigen klanten, een eigenaar of beheerder die van het kantoor. Verlaat dat lid de werkruimte, dan stopt de sleutel.

Limieten

Maximaal 120 aanroepen per minuut per sleutel. Daarboven is het antwoord 429 met RATE_LIMITED en retryAfterSec: wacht zoveel seconden en roep dan opnieuw aan.

Pagina's

GET /projects geeft maximaal 100 projecten tegelijk: limit zegt hoeveel, offset waar te beginnen, en total hoeveel er in totaal zijn.

Id's

Een projectsleutel komt uit GET /projects, een klant-id uit GET /clients, en een deal-id uit de klantkaart, GET /clients/{id}, in deals[].id.

Er gaat niets naar een klant

Geen enkele aanroep stuurt iets naar een klant: POST /brochures geeft een link terug die de makelaar zelf verstuurt. Prijzen zijn die van de ontwikkelaar, in de valuta van de ontwikkelaar.

Weigeringen

Een weigering is JSON met een vaste code. Ga uit van de code, nooit van de melding.

{ "code": "plan_required" }

Status	Code	Betekenis
401	key_required	Geen header Authorization met een sleutel.
401	key_invalid	De sleutel is onbekend of ingetrokken.
403	key_scope	De sleutel geeft geen toegang tot de REST API. Maak er een met REST API aangevinkt.
403	plan_required	De werkruimte heeft geen Agency-abonnement meer.
403	key_member_gone	Degene die de sleutel maakte, heeft de werkruimte verlaten. Maak een nieuwe sleutel.
404	not_found	Niet gevonden, of niet zichtbaar voor dit lid.
429	RATE_LIMITED	Te veel aanroepen deze minuut. Wacht retryAfterSec seconden.
400	place_unknown, whatsapp_invalid, …	Een veld buiten bereik of een ongeldige waarde. De code noemt het veld.

Referentie

Elke aanroep met de velden en een voorbeeld, zoals in het OpenAPI-document.

Basisadres

https://realton.ai/api/v1

Catalogus

GET/projectsSearch the catalog

Projects that fit, newest first, with their price from. Up to 100 a page.

Parameters

Naam	Type	Wat het is
q in de query	string ≤ 120	Words of a project's or a developer's name.
place in de query	string ≤ 80	A city or an emirate, by name or slug: Dubai, Batumi, Limassol.
area in de query	string ≤ 80	An area, by name or slug: Dubai Islands, JVC.
beds in de query	integer 0–9	Bedrooms: 0 is a studio, 4 is four and more.
maxPrice in de query	number	The most the client would pay, in `currency`.
currency in de query	string	The currency of `maxPrice`.
handoverBy in de query	integer 2025–2045	The latest handover year.
lang in de query	en \| he	The language of place and area names.
limit in de query	integer 1–100	How many projects in this page.
offset in de query	integer	How many to skip: the next page starts at offset + limit.

Antwoord 200

Naam	Type	Wat het is
totalverplicht	integer	How many projects fit, across all pages.
offsetverplicht	integer	The offset of this page.
catalogDateverplicht	string	The day the catalog was last built, YYYY-MM-DD.
projectsverplicht	array

Elk ervan

Naam	Type	Wat het is
key	string	The project key, for `GET /projects/{key}` and `POST /brochures`.
name	string	The project's name.
developer	string \| null	The developer's name.
market	ae \| cy \| ge \| om \| sa	ae, cy, ge, om or sa.
place	string \| null	The city or emirate.
area	string \| null	The area.
stage	OFF_PLAN \| UNDER_CONSTRUCTION \| READY	OFF_PLAN, UNDER_CONSTRUCTION or READY.
handover	string \| null	When it is handed over, as the developer says it: Q4 2028.
priceFrom	number \| null	The lowest price, in `currency`.
currency	string	The developer's currency: AED, EUR, USD, OMR, SAR.
bedrooms	array	The bedroom counts it has; 0 is a studio.
commissionPct	number \| null	The agent's commission, in percent.
photo	string \| null	A photo of it.

Voorbeeld

{
  "total": 312,
  "offset": 0,
  "catalogDate": "2026-10-24",
  "projects": [
    {
      "key": "studio:soma-residences",
      "name": "Soma Residences",
      "developer": "Origami Properties",
      "market": "ae",
      "place": "Dubai",
      "area": "Dubai Islands",
      "stage": "OFF_PLAN",
      "handover": "Q4 2028",
      "priceFrom": 1670000,
      "currency": "AED",
      "bedrooms": [
        1,
        2,
        3
      ],
      "commissionPct": 5,
      "photo": "https://…/soma-residences.avif"
    }
  ]
}

curl

curl -X GET "https://realton.ai/api/v1/projects" \
  -H "Authorization: Bearer $REALTON_API_KEY"

GET/projects/{key}One project in full

Unit types with sizes and prices, payment plans, amenities, the gallery and what is nearby.

Parameters

Naam	Type	Wat het is
keyverplicht in het pad	string	The project key from `GET /projects`.
lang in de query	en \| he	The language of names, plans and amenities.

Antwoord 200

Naam	Type	Wat het is
entry	object	Its catalog line: the same figures as `GET /projects`, with `title` for the name and slugs for place and area.
placeName	string \| null	The city or emirate.
areaName	string \| null	The area.
unitTypes	array	Each unit type: label, beds, available (from the inventory), sizeSqft, sizeSqm, priceFrom, currency, pricePerArea, areaUnit.
plans	array	Payment plans: each with its steps (label, timing, percent, phase) and its share before and after handover.
dldPct	number \| null	Dubai's registration fee on booking, in percent; null elsewhere.
amenities	array	What the project offers.
gallery	object	count, and images with their url.
nearby	array	Places near it: category, name, km.

curl

curl -X GET "https://realton.ai/api/v1/projects/{key}" \
  -H "Authorization: Bearer $REALTON_API_KEY"

Klanten

GET/clientsYour clients

An agent's own clients; an owner's or an admin's, the agency's. Last active first.

Parameters

Naam	Type	Wat het is
q in de query	string ≤ 80	A name, a number or an email to look for.

Antwoord 200

Naam	Type	Wat het is
clientsverplicht	array

Elk ervan

Naam	Type	Wat het is
id	string	The client id.
name	string \| null	Their name.
whatsapp	string \| null	Their number.
email	string \| null	Their email.
language	string \| null	The language they speak.
source	string	Where they came from.
stage	NEW \| CONTACTED \| VIEWING \| EOI \| BOOKED \| WON \| LOST	The stage of their most advanced open deal.
project	string \| null	The project of that deal.
lastActivityAt	string	The last thing that happened with them, ISO date-time.
ownerUserId	string	The member they belong to.
openTasks	integer	Their open tasks.

curl

curl -X GET "https://realton.ai/api/v1/clients" \
  -H "Authorization: Bearer $REALTON_API_KEY"

POST/clientsA new client

A name and at least one way to reach them is the usual; a name alone is accepted.

Body

Naam	Type	Wat het is
nameverplicht	string ≤ 120	Their full name.
whatsapp	string ≤ 30	A number with its country code, +971 50 555 0147.
email	string ≤ 200	An email address.
language	string ≤ 5	The language they speak, a two-letter code: en, ar, he, ru…

Voorbeeld

{
  "name": "Elena Petrova",
  "whatsapp": "+971505550147",
  "language": "ru"
}

Antwoord 201

Naam	Type	Wat het is
id	string	The client id.
name	string \| null	Their name.
language	string \| null	The language they speak.
whatsapp	string \| null	Their number, E.164.
email	string \| null	Their email.
ownerUserId	string	The member they belong to.
updatedAt	string	ISO date-time.

curl

curl -X POST "https://realton.ai/api/v1/clients" \
  -H "Authorization: Bearer $REALTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Elena Petrova","whatsapp":"+971505550147","language":"ru"}'

GET/clients/{id}A client's card

Their details, what they are looking for, and their deals with each deal's id for PATCH /deals/{id}.

Parameters

Naam	Type	Wat het is
idverplicht in het pad	string	The client id from `GET /clients`.
lang in de query	en \| he	The language of place names.

Antwoord 200

Naam	Type	Wat het is
id	string	The client id.
name	string \| null	Their name.
whatsapp	string \| null	Their number.
email	string \| null	Their email.
language	string \| null	The language they speak.
requirements	object	What they are looking for: places, bedrooms, budget, handover.
ownerName	string \| null	The member they belong to.
deals	array	Their deals: id, stage, projectKey, projectTitle, beds, unitLabel, price, currency, commissionPct, commission, lostReason.

curl

curl -X GET "https://realton.ai/api/v1/clients/{id}" \
  -H "Authorization: Bearer $REALTON_API_KEY"

POST/clients/{id}/notesA note on a client's card

Free text on the client's timeline, as the member.

Parameters

Naam	Type	Wat het is
idverplicht in het pad	string	The client id.

Body

Naam	Type	Wat het is
textverplicht	string ≤ 4000	The note.

Voorbeeld

{
  "text": "Wants a sea view, budget AED 2M, moving in 2028."
}

Antwoord 201

Naam	Type	Wat het is
idverplicht	string	The note id.

curl

curl -X POST "https://realton.ai/api/v1/clients/{id}/notes" \
  -H "Authorization: Bearer $REALTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Wants a sea view, budget AED 2M, moving in 2028."}'

Taken

GET/tasksYour tasks

The member's own tasks, with how many there are in each scope.

Parameters

Naam	Type	Wat het is
scope in de query	open \| overdue \| today \| upcoming \| someday \| done	open is every task not done.

Antwoord 200

Naam	Type	Wat het is
tasksverplicht	array
countsverplicht	object	How many tasks in overdue, today, upcoming, someday and done.

Elk ervan

Naam	Type	Wat het is
id	string	The task id.
title	string	What to do.
note	string \| null	More words about it.
dueAt	string \| null	When, ISO date-time.
dueKind	AT \| DAY \| NONE	AT, DAY or NONE.
doneAt	string \| null	When it was done.
scope	overdue \| today \| upcoming \| someday \| done	Where it stands now, in the member's time zone.
contact	object \| null	The client it is for: id and name.
dealId	string \| null	The deal it belongs to.

curl

curl -X GET "https://realton.ai/api/v1/tasks" \
  -H "Authorization: Bearer $REALTON_API_KEY"

POST/tasksA new task

A task at a time, on a day, or with no date; for a client when clientId is given.

Body

Naam	Type	Wat het is
titleverplicht	string ≤ 200	What to do.
note	string ≤ 2000	More words about it.
dueAt	string ≤ 40	When: an ISO date-time with its offset, 2026-10-25T11:00:00+04:00. With dueKind DAY, any time on that day.
dueKind	AT \| DAY \| NONE	AT for a time, DAY for a whole day, NONE for no date.
clientId	string	The client the task is for.

Voorbeeld

{
  "title": "Call Elena about Soma Residences",
  "dueAt": "2026-10-25T11:00:00+04:00",
  "dueKind": "AT",
  "clientId": "cm2x8k1qz0001abcdeffghijk"
}

Antwoord 201

Naam	Type	Wat het is
id	string	The task id.
title	string	What to do.
note	string \| null	More words about it.
dueAt	string \| null	When, ISO date-time.
dueKind	AT \| DAY \| NONE	AT, DAY or NONE.
doneAt	string \| null	When it was done.
scope	overdue \| today \| upcoming \| someday \| done	Where it stands now, in the member's time zone.
contact	object \| null	The client it is for: id and name.
dealId	string \| null	The deal it belongs to.

curl

curl -X POST "https://realton.ai/api/v1/tasks" \
  -H "Authorization: Bearer $REALTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Call Elena about Soma Residences","dueAt":"2026-10-25T11:00:00+04:00","dueKind":"AT","clientId":"cm2x8k1qz0001abcdeffghijk"}'

Deals

PATCH/deals/{id}Move a deal's stage

A deal's id is on its client's card (GET /clients/{id}, deals[].id).

Parameters

Naam	Type	Wat het is
idverplicht in het pad	string	The deal id.

Body

Naam	Type	Wat het is
stageverplicht	NEW \| CONTACTED \| VIEWING \| EOI \| BOOKED \| WON \| LOST	The new stage.
lostReason	string ≤ 200	Why it was lost; read only with LOST.

Voorbeeld

{
  "stage": "VIEWING"
}

Antwoord 200

Naam	Type	Wat het is
okverplicht	boolean

curl

curl -X PATCH "https://realton.ai/api/v1/deals/{id}" \
  -H "Authorization: Bearer $REALTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stage":"VIEWING"}'

Brochures

POST/brochuresA brochure link

A brochure of a project in your brand, with open tracking, for the agent to send. Realton does not send it.

Body

Naam	Type	Wat het is
projectverplicht	string	The project key.
clientId	string	The client it is for: their opens show on their card.
langverplicht	en \| he	The language of the brochure.

Voorbeeld

{
  "project": "studio:soma-residences",
  "clientId": "cm2x8k1qz0001abcdeffghijk",
  "lang": "en"
}

Antwoord 201

Naam	Type	Wat het is
idverplicht	string	The link id.
urlverplicht	string	The address to send: it opens the brochure in the agency's brand.
projectverplicht	string	The project name.
langverplicht	string	The language of the brochure.
clientverplicht	string \| null	The client's name, when it is for one.

Voorbeeld

{
  "id": "cm2x9p0aa0002abcdeffghijk",
  "url": "https://realton.ai/b/Hk3…",
  "project": "Soma Residences",
  "lang": "en",
  "client": "Elena Petrova"
}

curl

curl -X POST "https://realton.ai/api/v1/brochures" \
  -H "Authorization: Bearer $REALTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project":"studio:soma-residences","clientId":"cm2x8k1qz0001abcdeffghijk","lang":"en"}'