REST API

The REST API

Your systems read Realton's catalog and your CRM, and write clients, notes, tasks and deal stages, as the person who made the key.

Business plan

Quick start

In Realton, an owner or an admin opens Settings › API and MCP, ticks REST API and chooses Make a key. Copy it right away: it is shown once.
Keep it on your server, in an environment variable:
```
export REALTON_API_KEY="rtk_live_…"
```

Make your first call:

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

Building it with an AI

Most integrations are written by an AI today. Give it these two addresses and the task in a few words; it reads the rest by itself.

The brief /docs/api.mdOpenAPI 3.1 /docs/openapi.json

A prompt to copy, with the brackets filled in:

I want to connect [my website / my CRM / my system] to Realton's REST API.
Read the brief first: https://realton.ai/docs/api.md
The full OpenAPI document: https://realton.ai/docs/openapi.json
My stack: [for example, Next.js on Vercel].
What I want: [for example, show Realton's projects in Dubai on my site, refreshed once a day].
The API key is in the environment variable REALTON_API_KEY. Never ask me for the key and never write it into the code.

Never paste the key into a chat. Set REALTON_API_KEY on the server yourself, and tell the AI only its name.

The rules

The key

Every call sends the key in the Authorization header. A key opens the REST API only if REST API was ticked when it was made, and only while the workspace is on Business.

Authorization: Bearer rtk_live_…

Who a call acts as

A call acts as the member who made the key, with what they can see: an agent their own clients, an owner or an admin the agency's. When that member leaves the workspace, the key stops.

Limits

Up to 120 calls a minute per key. Over that, the answer is 429 with RATE_LIMITED and retryAfterSec: wait that many seconds and call again.

Pages

GET /projects returns up to 100 projects at a time: limit says how many, offset where to start, and total how many there are in all.

Ids

A project key comes from GET /projects, a client id from GET /clients, and a deal id from the client's card, GET /clients/{id}, in deals[].id.

Nothing goes to a client

No call sends anything to a client: POST /brochures returns a link for the agent to send. Prices are the developer's own, in the developer's currency.

Refusals

A refusal is JSON with a stable code. Switch on the code, never on the message.

{ "code": "plan_required" }

Status	Code	What it means
401	key_required	No Authorization header with a key.
401	key_invalid	The key is unknown or was revoked.
403	key_scope	The key does not open the REST API. Make one with REST API ticked.
403	plan_required	The workspace is no longer on Business.
403	key_member_gone	The person who made the key left the workspace. Make a new key.
404	not_found	Not found, or not this member's to see.
429	RATE_LIMITED	Too many calls this minute. Wait retryAfterSec seconds.
400	place_unknown, whatsapp_invalid, …	A field out of range or a value that is not one. The code names it.

Reference

Every call with its fields and an example, as in the OpenAPI document.

Base address

https://realton.ai/api/v1

Catalog

GET/projectsSearch the catalog

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

Parameters

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

Answer 200

Name	Type	What it is
totalrequired	integer	How many projects fit, across all pages.
offsetrequired	integer	The offset of this page.
catalogDaterequired	string	The day the catalog was last built, YYYY-MM-DD.
projectsrequired	array

Each of them

Name	Type	What it 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.

Example

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

Name	Type	What it is
keyrequired in the path	string	The project key from `GET /projects`.
lang in the query	en \| he	The language of names, plans and amenities.

Answer 200

Name	Type	What it 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"

Clients

GET/clientsYour clients

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

Parameters

Name	Type	What it is
q in the query	string ≤ 80	A name, a number or an email to look for.

Answer 200

Name	Type	What it is
clientsrequired	array

Each of them

Name	Type	What it 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

Name	Type	What it is
namerequired	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…

Example

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

Answer 201

Name	Type	What it 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

Name	Type	What it is
idrequired in the path	string	The client id from `GET /clients`.
lang in the query	en \| he	The language of place names.

Answer 200

Name	Type	What it 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

Name	Type	What it is
idrequired in the path	string	The client id.

Body

Name	Type	What it is
textrequired	string ≤ 4000	The note.

Example

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

Answer 201

Name	Type	What it is
idrequired	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."}'

Tasks

GET/tasksYour tasks

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

Parameters

Name	Type	What it is
scope in the query	open \| overdue \| today \| upcoming \| someday \| done	open is every task not done.

Answer 200

Name	Type	What it is
tasksrequired	array
countsrequired	object	How many tasks in overdue, today, upcoming, someday and done.

Each of them

Name	Type	What it 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

Name	Type	What it is
titlerequired	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.

Example

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

Answer 201

Name	Type	What it 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

Name	Type	What it is
idrequired in the path	string	The deal id.

Body

Name	Type	What it is
stagerequired	NEW \| CONTACTED \| VIEWING \| EOI \| BOOKED \| WON \| LOST	The new stage.
lostReason	string ≤ 200	Why it was lost; read only with LOST.

Example

{
  "stage": "VIEWING"
}

Answer 200

Name	Type	What it is
okrequired	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

Name	Type	What it is
projectrequired	string	The project key.
clientId	string	The client it is for: their opens show on their card.
langrequired	en \| he	The language of the brochure.

Example

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

Answer 201

Name	Type	What it is
idrequired	string	The link id.
urlrequired	string	The address to send: it opens the brochure in the agency's brand.
projectrequired	string	The project name.
langrequired	string	The language of the brochure.
clientrequired	string \| null	The client's name, when it is for one.

Example

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