REST API

Sistemele dumneavoastră citesc catalogul Realton și CRM-ul și scriu clienți, note, sarcini și etape ale tranzacțiilor, în numele persoanei care a creat cheia.

Abonamentul Agency

Primii pași

În Realton, titularul sau un administrator deschide Setări › API și MCP, bifează REST API și alege Creați o cheie. Copiați-o imediat: este afișată o singură dată.
Păstrați-o pe server, într-o variabilă de mediu:
```
export REALTON_API_KEY="rtk_live_…"
```

Faceți primul apel:

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

Cu ajutorul unui AI

Astăzi, cele mai multe integrări le scrie un AI. Dați-i aceste două adrese și sarcina în câteva cuvinte; restul îl citește singur.

Rezumatul /docs/api.mdOpenAPI 3.1 /docs/openapi.json

Un prompt de copiat, cu parantezele completate:

Vreau să conectez [site-ul meu / CRM-ul meu / sistemul meu] la REST API-ul Realton.
Citește mai întâi rezumatul: https://realton.ai/docs/api.md
Documentul OpenAPI complet: https://realton.ai/docs/openapi.json
Tehnologiile mele: [de exemplu, Next.js pe Vercel].
Ce vreau: [de exemplu, să afișez pe site proiectele Realton din Dubai, actualizate o dată pe zi].
Cheia API este în variabila de mediu REALTON_API_KEY. Nu-mi cere niciodată cheia și nu o scrie niciodată în cod.

Nu lipiți niciodată cheia într-o conversație. Setați chiar dumneavoastră REALTON_API_KEY pe server și spuneți-i AI-ului doar numele variabilei.

Regulile

Cheia

Fiecare apel trimite cheia în antetul Authorization. O cheie dă acces la REST API doar dacă la creare a fost bifat REST API și doar cât timp spațiul de lucru are abonamentul Agency.

Authorization: Bearer rtk_live_…

În numele cui acționează un apel

Un apel acționează în numele membrului care a creat cheia, cu ce vede acesta: un agent, pe propriii clienți; titularul sau un administrator, pe cei ai agenției. Când membrul părăsește spațiul de lucru, cheia nu mai funcționează.

Limite

Până la 120 de apeluri pe minut pentru fiecare cheie. Peste această limită, răspunsul este 429 cu RATE_LIMITED și retryAfterSec: așteptați numărul indicat de secunde și apelați din nou.

Paginare

GET /projects întoarce până la 100 de proiecte o dată: limit spune câte, offset de unde se începe, iar total câte sunt în total.

Identificatori

Cheia unui proiect vine din GET /projects, id-ul unui client din GET /clients, iar id-ul unei tranzacții din fișa clientului, GET /clients/{id}, în deals[].id.

Nimic nu ajunge la client

Niciun apel nu trimite ceva unui client: POST /brochures întoarce un link pe care îl trimite agentul. Prețurile sunt cele ale dezvoltatorului, în moneda dezvoltatorului.

Refuzuri

Un refuz este un JSON cu un code stabil. Decideți după cod, niciodată după mesaj.

{ "code": "plan_required" }

Status	Cod	Ce înseamnă
401	key_required	Lipsește antetul Authorization cu o cheie.
401	key_invalid	Cheia este necunoscută sau a fost revocată.
403	key_scope	Cheia nu dă acces la REST API. Creați una cu REST API bifat.
403	plan_required	Spațiul de lucru nu mai are abonamentul Agency.
403	key_member_gone	Persoana care a creat cheia a părăsit spațiul de lucru. Creați o cheie nouă.
404	not_found	Nu a fost găsit sau acest membru nu are acces la el.
429	RATE_LIMITED	Prea multe apeluri în acest minut. Așteptați retryAfterSec secunde.
400	place_unknown, whatsapp_invalid, …	Un câmp în afara intervalului sau o valoare care nu este permisă. Codul îl numește.

Referință

Fiecare apel, cu câmpurile lui și un exemplu, ca în documentul OpenAPI.

Adresa de bază

https://realton.ai/api/v1

Catalog

GET/projectsSearch the catalog

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

Parametri

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

Răspuns 200

Nume	Tip	Ce este
totalobligatoriu	integer	How many projects fit, across all pages.
offsetobligatoriu	integer	The offset of this page.
catalogDateobligatoriu	string	The day the catalog was last built, YYYY-MM-DD.
projectsobligatoriu	array

Fiecare dintre ele

Nume	Tip	Ce este
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.

Exemplu

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

Parametri

Nume	Tip	Ce este
keyobligatoriu în cale	string	The project key from `GET /projects`.
lang în interogare	en \| he	The language of names, plans and amenities.

Răspuns 200

Nume	Tip	Ce este
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"

Clienți

GET/clientsYour clients

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

Parametri

Nume	Tip	Ce este
q în interogare	string ≤ 80	A name, a number or an email to look for.

Răspuns 200

Nume	Tip	Ce este
clientsobligatoriu	array

Fiecare dintre ele

Nume	Tip	Ce este
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.

Corp

Nume	Tip	Ce este
nameobligatoriu	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…

Exemplu

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

Răspuns 201

Nume	Tip	Ce este
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}.

Parametri

Nume	Tip	Ce este
idobligatoriu în cale	string	The client id from `GET /clients`.
lang în interogare	en \| he	The language of place names.

Răspuns 200

Nume	Tip	Ce este
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.

Parametri

Nume	Tip	Ce este
idobligatoriu în cale	string	The client id.

Corp

Nume	Tip	Ce este
textobligatoriu	string ≤ 4000	The note.

Exemplu

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

Răspuns 201

Nume	Tip	Ce este
idobligatoriu	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."}'

Sarcini

GET/tasksYour tasks

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

Parametri

Nume	Tip	Ce este
scope în interogare	open \| overdue \| today \| upcoming \| someday \| done	open is every task not done.

Răspuns 200

Nume	Tip	Ce este
tasksobligatoriu	array
countsobligatoriu	object	How many tasks in overdue, today, upcoming, someday and done.

Fiecare dintre ele

Nume	Tip	Ce este
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.

Corp

Nume	Tip	Ce este
titleobligatoriu	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.

Exemplu

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

Răspuns 201

Nume	Tip	Ce este
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"}'

Tranzacții

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

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

Parametri

Nume	Tip	Ce este
idobligatoriu în cale	string	The deal id.

Corp

Nume	Tip	Ce este
stageobligatoriu	NEW \| CONTACTED \| VIEWING \| EOI \| BOOKED \| WON \| LOST	The new stage.
lostReason	string ≤ 200	Why it was lost; read only with LOST.

Exemplu

{
  "stage": "VIEWING"
}

Răspuns 200

Nume	Tip	Ce este
okobligatoriu	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"}'

Broșuri

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.

Corp

Nume	Tip	Ce este
projectobligatoriu	string	The project key.
clientId	string	The client it is for: their opens show on their card.
langobligatoriu	en \| he	The language of the brochure.

Exemplu

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

Răspuns 201

Nume	Tip	Ce este
idobligatoriu	string	The link id.
urlobligatoriu	string	The address to send: it opens the brochure in the agency's brand.
projectobligatoriu	string	The project name.
langobligatoriu	string	The language of the brochure.
clientobligatoriu	string \| null	The client's name, when it is for one.

Exemplu

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