REST API

Die REST API

Ihre Systeme lesen den Katalog von Realton und Ihr CRM und schreiben Kunden, Notizen, Aufgaben und Deal-Phasen, im Namen der Person, die den Schlüssel erstellt hat.

Tarif Agency

Schnellstart

In Realton öffnet der Inhaber oder ein Admin Einstellungen › API und MCP, setzt das Häkchen bei REST API und wählt Schlüssel erstellen. Kopieren Sie ihn sofort: Er wird nur einmal angezeigt.
Bewahren Sie ihn auf Ihrem Server in einer Umgebungsvariablen auf:
```
export REALTON_API_KEY="rtk_live_…"
```

Ihr erster Aufruf:

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

Mit einer KI entwickeln

Die meisten Integrationen schreibt heute eine KI. Geben Sie ihr diese beiden Adressen und die Aufgabe in wenigen Worten, den Rest liest sie selbst.

Das Briefing /docs/api.mdOpenAPI 3.1 /docs/openapi.json

Ein Prompt zum Kopieren, mit ausgefüllten Klammern:

Ich möchte [meine Website / mein CRM / mein System] an die REST API von Realton anbinden.
Lies zuerst das Briefing: https://realton.ai/docs/api.md
Das vollständige OpenAPI-Dokument: https://realton.ai/docs/openapi.json
Mein Stack: [zum Beispiel Next.js auf Vercel].
Was ich möchte: [zum Beispiel die Projekte von Realton in Dubai auf meiner Website zeigen, einmal täglich aktualisiert].
Der API-Schlüssel liegt in der Umgebungsvariablen REALTON_API_KEY. Frag mich nie nach dem Schlüssel und schreib ihn nie in den Code.

Fügen Sie den Schlüssel nie in einen Chat ein. Setzen Sie REALTON_API_KEY selbst auf dem Server und nennen Sie der KI nur den Namen.

Die Regeln

Der Schlüssel

Jeder Aufruf sendet den Schlüssel im Header Authorization. Ein Schlüssel öffnet die REST API nur, wenn beim Erstellen REST API angehakt war, und nur, solange der Arbeitsbereich im Tarif Agency ist.

Authorization: Bearer rtk_live_…

In wessen Namen ein Aufruf handelt

Ein Aufruf handelt im Namen des Mitglieds, das den Schlüssel erstellt hat, mit dessen Sichtbarkeit: ein Makler mit seinen eigenen Kunden, der Inhaber oder ein Admin mit denen des Maklerbüros. Verlässt dieses Mitglied den Arbeitsbereich, funktioniert der Schlüssel nicht mehr.

Limits

Bis zu 120 Aufrufe pro Minute und Schlüssel. Darüber lautet die Antwort 429 mit RATE_LIMITED und retryAfterSec: Warten Sie so viele Sekunden und rufen Sie dann erneut auf.

Seiten

GET /projects liefert bis zu 100 Projekte auf einmal: limit gibt an, wie viele, offset, ab wo, und total, wie viele es insgesamt sind.

IDs

Einen Projektschlüssel liefert GET /projects, eine Kunden-ID GET /clients und eine Deal-ID die Kundenkarte, GET /clients/{id}, in deals[].id.

Nichts geht an Kunden

Kein Aufruf schickt etwas an einen Kunden: POST /brochures liefert einen Link, den der Makler versendet. Die Preise sind die des Bauträgers, in seiner Währung.

Ablehnungen

Eine Ablehnung ist JSON mit einem festen code. Werten Sie den Code aus, nie die Meldung.

{ "code": "plan_required" }

Status	Code	Bedeutung
401	key_required	Kein Authorization-Header mit Schlüssel.
401	key_invalid	Der Schlüssel ist unbekannt oder wurde widerrufen.
403	key_scope	Der Schlüssel öffnet die REST API nicht. Erstellen Sie einen mit Häkchen bei REST API.
403	plan_required	Der Arbeitsbereich ist nicht mehr im Tarif Agency.
403	key_member_gone	Die Person, die den Schlüssel erstellt hat, hat den Arbeitsbereich verlassen. Erstellen Sie einen neuen Schlüssel.
404	not_found	Nicht gefunden, oder für dieses Mitglied nicht sichtbar.
429	RATE_LIMITED	Zu viele Aufrufe in dieser Minute. Warten Sie retryAfterSec Sekunden.
400	place_unknown, whatsapp_invalid, …	Ein Feld außerhalb des zulässigen Bereichs oder ein ungültiger Wert. Der Code nennt das Feld.

Referenz

Jeder Aufruf mit seinen Feldern und einem Beispiel, wie im OpenAPI-Dokument.

Basisadresse

https://realton.ai/api/v1

Katalog

GET/projectsSearch the catalog

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

Parameter

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

Antwort 200

Name	Typ	Bedeutung
totalPflicht	integer	How many projects fit, across all pages.
offsetPflicht	integer	The offset of this page.
catalogDatePflicht	string	The day the catalog was last built, YYYY-MM-DD.
projectsPflicht	array

Jedes Element

Name	Typ	Bedeutung
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.

Beispiel

{
  "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.

Parameter

Name	Typ	Bedeutung
keyPflicht im Pfad	string	The project key from `GET /projects`.
lang in der Query	en \| he	The language of names, plans and amenities.

Antwort 200

Name	Typ	Bedeutung
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"

Kunden

GET/clientsYour clients

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

Parameter

Name	Typ	Bedeutung
q in der Query	string ≤ 80	A name, a number or an email to look for.

Antwort 200

Name	Typ	Bedeutung
clientsPflicht	array

Jedes Element

Name	Typ	Bedeutung
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

Name	Typ	Bedeutung
namePflicht	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…

Beispiel

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

Antwort 201

Name	Typ	Bedeutung
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}.

Parameter

Name	Typ	Bedeutung
idPflicht im Pfad	string	The client id from `GET /clients`.
lang in der Query	en \| he	The language of place names.

Antwort 200

Name	Typ	Bedeutung
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.

Parameter

Name	Typ	Bedeutung
idPflicht im Pfad	string	The client id.

Body

Name	Typ	Bedeutung
textPflicht	string ≤ 4000	The note.

Beispiel

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

Antwort 201

Name	Typ	Bedeutung
idPflicht	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."}'

Aufgaben

GET/tasksYour tasks

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

Parameter

Name	Typ	Bedeutung
scope in der Query	open \| overdue \| today \| upcoming \| someday \| done	open is every task not done.

Antwort 200

Name	Typ	Bedeutung
tasksPflicht	array
countsPflicht	object	How many tasks in overdue, today, upcoming, someday and done.

Jedes Element

Name	Typ	Bedeutung
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

Name	Typ	Bedeutung
titlePflicht	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.

Beispiel

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

Antwort 201

Name	Typ	Bedeutung
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).

Parameter

Name	Typ	Bedeutung
idPflicht im Pfad	string	The deal id.

Body

Name	Typ	Bedeutung
stagePflicht	NEW \| CONTACTED \| VIEWING \| EOI \| BOOKED \| WON \| LOST	The new stage.
lostReason	string ≤ 200	Why it was lost; read only with LOST.

Beispiel

{
  "stage": "VIEWING"
}

Antwort 200

Name	Typ	Bedeutung
okPflicht	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"}'

Broschüren

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

Name	Typ	Bedeutung
projectPflicht	string	The project key.
clientId	string	The client it is for: their opens show on their card.
langPflicht	en \| he	The language of the brochure.

Beispiel

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

Antwort 201

Name	Typ	Bedeutung
idPflicht	string	The link id.
urlPflicht	string	The address to send: it opens the brochure in the agency's brand.
projectPflicht	string	The project name.
langPflicht	string	The language of the brochure.
clientPflicht	string \| null	The client's name, when it is for one.

Beispiel

{
  "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"}'