Resources
| Path | Scope | Id |
|---|---|---|
/api/v1/clients, /api/v1/clients/{id} | clients:read | integer |
/api/v1/properties, /api/v1/properties/{id} | properties:read | UUID |
/api/v1/deals, /api/v1/deals/{id} | deals:read | UUID |
/api/v1/events, /api/v1/events/{id} | events:read | integer |
/api/v1/leads, /api/v1/leads/{id} | leads:read | UUID |
/api/v1/tasks, /api/v1/tasks/{id} | tasks:read | UUID |
Field lists are in the OpenAPI document. They're deliberately narrow: no portal/provider payloads, AI output, internal notes, commission or settlement data, cost fields, land-register numbers or key/access notes. assigned_user_id is the same field name on every resource (on deals it maps to the assignee).
Two deliberate exceptions on leads (2026-10-30, for portal integrations): message is the text of the inquiry as received from the portal e-mail and is returned only when source is email_import (for leads typed in by an agent the same column holds their own notes, which stay internal and come back as null); portal, offer_number, provider_listing_id and listing_title come from the import record of that inquiry (lead_inquiry_sources) and are null for leads that were not imported.
Visibility follows the office setting "Widoczność danych między agentami" (Settings → Office) the same way the web app does: a key or an AI connector grant of an AGENT reads every client and property of the office when the office is set to "Pełne biuro (odczyt)" and its plan is active; deals, events, inquiries and tasks stay limited to the agent's own records, and leadership roles always read the whole office.
Listings in the Estalo trash are never returned. Clients with status archived (and its legacy twin closed) are left out of lists unless you pass include_archived=true; a client fetched by id is returned regardless of status.
A record that belongs to another office, or one your key can't see, answers 404, exactly like an id that doesn't exist.
Clients (clients)
Clients (buyers, sellers, landlords) of the office.
- Paths
- /api/v1/clients, /api/v1/clients/{id} (integer)
- Read
- clients:read
- Write
- clients:write
- DELETE
- archives the client
| Field | Type | Write | Description |
|---|---|---|---|
id | integer | read-only | |
status | string | null | POST, PATCH | new, contacted, meeting, active, lost, archived (open/closed are legacy twins).Values: new, contacted, meeting, active, lost, archived |
type | string | null | POST, PATCH | buyer, seller or landlord.Values: buyer, seller, landlord |
first_name | string | null | POST, PATCH | |
last_name | string | null | POST, PATCH | |
name | string | null | POST, PATCH | Full name; first_name/last_name are derived from it when they are not sent. |
email | string | null | POST, PATCH (null clears) | |
phone | string | null | POST, PATCH (null clears) | |
interest | string | null | read-only | |
budget | number | null | POST, PATCH (null clears) | |
pref_budget_min | number | null | read-only | |
pref_budget_max | number | null | read-only | |
pref_area_min | number | null | read-only | |
pref_rooms_min | integer | null | read-only | |
pref_locations | string | null | read-only | |
assigned_user_id | uuid | null | read-only | |
last_contact_at | date-time | null | read-only | |
created_at | date-time | null | read-only | |
updated_at | date-time | null | read-only |
Listings (properties)
Listings (offers) of the office. Listings in the trash are never returned.
- Paths
- /api/v1/properties, /api/v1/properties/{id} (UUID)
- Read
- properties:read
- Write
- properties:write
- DELETE
- moves the listing to the trash
| Field | Type | Write | Description |
|---|---|---|---|
id | uuid | read-only | |
title | string | POST (required), PATCH | |
status | string | POST, PATCH | Values: active, reserved, sold, rented, inactive, offer |
offer_number | string | null | read-only | |
type | string | null | POST (required), PATCH | Values: flat, house, plot, store, warehouse, garage, room |
category | string | null | read-only | |
transaction_type | string | null | POST, PATCH | Values: sale, rent |
market | string | null | POST, PATCH | Values: primary, secondary |
price | number | null | POST (required), PATCH | |
area | number | null | POST, PATCH | |
rooms | integer | null | POST, PATCH | |
floor | integer | null | POST, PATCH (null clears) | |
total_floors | integer | null | POST, PATCH (null clears) | |
build_year | integer | null | POST, PATCH (null clears) | |
address_city | string | null | POST (required), PATCH | |
address_district | string | null | POST, PATCH | |
address_street | string | null | POST, PATCH | |
description | string | null | POST, PATCH | Public listing description. |
assigned_user_id | uuid | null | PATCH (null clears) | Office leadership on an active office plan only; otherwise 403 forbidden. |
created_at | date-time | null | read-only | |
updated_at | date-time | null | read-only |
Sales (deals)
Sales: transactions joining a client to a listing. Commission and settlement fields are not exposed.
- Paths
- /api/v1/deals, /api/v1/deals/{id} (UUID)
- Read
- deals:read
- Write
- deals:write
- DELETE
- none; change it with PATCH
| Field | Type | Write | Description |
|---|---|---|---|
id | uuid | read-only | |
title | string | POST (required), PATCH | |
stage | string | POST (required), PATCH | Values: new, presentation, negotiation, agreement, closed |
value | number | null | POST (required), PATCH | |
client_id | integer | null | POST, PATCH (null clears) | |
property_id | uuid | null | POST, PATCH (null clears) | |
assigned_user_id | uuid | null | POST, PATCH | Office leadership on an active office plan only; otherwise 403 forbidden. |
close_date | date-time | null | POST, PATCH (null clears) | |
created_at | date-time | null | read-only | |
updated_at | date-time | null | read-only |
Calendar events (events)
Calendar events (meetings, presentations, calls, notary appointments).
- Paths
- /api/v1/events, /api/v1/events/{id} (integer)
- Read
- events:read
- Write
- events:write
- DELETE
- deletes the record
| Field | Type | Write | Description |
|---|---|---|---|
id | integer | read-only | |
title | string | POST (required), PATCH | |
type | string | POST, PATCH | Values: meeting, test_drive, other, call, notary |
start_time | date-time | POST (required), PATCH | |
end_time | date-time | POST (required), PATCH | |
client_id | integer | null | POST, PATCH (null clears) | |
property_id | uuid | null | POST, PATCH (null clears) | |
assigned_user_id | uuid | null | read-only | |
outcome | string | null | PATCH (null clears) | Result of a held meeting; sets outcome_at.Values: interested, too_expensive, location, layout, to_negotiate, not_interested |
outcome_at | date-time | null | read-only | |
created_at | date-time | null | read-only | |
updated_at | date-time | null | read-only |
Inquiries (leads)
Inquiries (leads) from portals, forms and e-mail import.
- Paths
- /api/v1/leads, /api/v1/leads/{id} (UUID)
- Read
- leads:read
- Write
- leads:write
- DELETE
- none; change it with PATCH
| Field | Type | Write | Description |
|---|---|---|---|
id | uuid | read-only | |
status | string | null | POST, PATCH | Values: new, no_answer, callback, contacted, interested, meeting, negotiating, converted, not_interested, stale |
source | string | null | POST, PATCH | Free text; email_import is reserved for Estalo's mail import. |
message | string | null | POST, PATCH (null clears) | Text of the inquiry as received from the portal e-mail (source = email_import); null for other sources. Inquiry text. Returned by GET only for source = email_import, so it is write-only for other sources. |
first_name | string | null | POST, PATCH | |
last_name | string | null | POST, PATCH | |
customer_name | string | null | POST, PATCH | |
email | string | null | POST, PATCH (null clears) | |
phone | string | null | POST, PATCH (null clears) | |
marketing_consent | boolean | null | read-only | |
property_id | uuid | null | read-only | |
converted_client_id | integer | null | read-only | |
assigned_user_id | uuid | null | PATCH (null clears) | Office leadership on an active office plan only; otherwise 403 forbidden. |
created_at | date-time | null | read-only | |
updated_at | date-time | read-only | |
portal | string | null | read-only | otodom, nieruchomosci_online, gratka, morizon, adresowo or unknown. |
offer_number | string | null | read-only | Office listing number quoted by the portal. |
provider_listing_id | string | null | read-only | Listing id on the portal. |
listing_title | string | null | read-only |
Tasks (tasks)
Tasks and reminders.
- Paths
- /api/v1/tasks, /api/v1/tasks/{id} (UUID)
- Read
- tasks:read
- Write
- tasks:write
- DELETE
- deletes the record
| Field | Type | Write | Description |
|---|---|---|---|
id | uuid | read-only | |
title | string | POST (required), PATCH | |
status | string | null | POST, PATCH | todo, in_progress or done.Values: todo, in_progress, done |
priority | string | null | POST, PATCH | Values: low, medium, high |
task_type | string | null | POST, PATCH | Values: call, meeting, viewing, other |
due_date | date-time | POST, PATCH | |
completed_at | date-time | null | read-only | |
related_client_id | integer | null | POST, PATCH (null clears) | |
related_property_id | uuid | null | POST, PATCH (null clears) | |
related_deal_id | uuid | null | POST, PATCH (null clears) | |
assigned_user_id | uuid | null | POST, PATCH | Office leadership on an active office plan only; otherwise 403 forbidden. |
created_at | date-time | null | read-only | |
updated_at | date-time | null | read-only |