Changing data

Changing data

Who can write

A key changes data only when all of these hold:

1. The office owner has switched changes on, once, under Settings › API and webhooks › Changes through the API. It needs a confirmed e-mail address and, when two-step verification is on, a session confirmed with the code. Until then keys can only read and /me says writes: not_activated.
2. The key has the write scope of the resource. Keys with any write scope can be created or replaced only by an owner who has two-step verification switched on and confirmed this sign-in with the code.
3. The key's creator could make the same change in Estalo. A write runs as that person, through the same rules as the web and mobile apps: office membership, role, which records are assigned to them, plan limits, duplicate checks. An agent's key changes only the agent's records. Assigning a record to someone (assigned_user_id) is for owners, managers and directors on an office plan.
4. The key's creator still has two-step verification on. If they switch it off, the key keeps reading but every write answers 401 api_key_inactive until they switch it on again.
5. The creator is working in the key's office at that moment. If they switched to another office in Estalo, writes answer 409 creator_context_mismatch until they switch back; nothing is written elsewhere.

The owner can switch changes off again in the same place (it needs a sign-in confirmed with the code when two-step verification is on). Write keys then keep reading, every write answers 403 writes_not_enabled, and no new write key can be created until changes are switched on again.

The database checks the scope again on every row it writes, so a key without clients:write cannot insert a client even through a code path we forgot.

Operations

Inquiries and sales have no DELETE: change their status or stage. The response carries the record in the same shape as GET when the key also has the read scope, otherwise only { "id": … }.

Bodies are JSON objects (Content-Type: application/json) of at most 64 KB. A field that is unknown or read-only answers 400 invalid_request with param; nothing is silently dropped. The writable fields per resource are in the OpenAPI document (ClientCreate, ClientUpdate, …). In short:

Notes: timestamps need a time zone. A task links to at most one record: sending one related_* replaces the link, null removes it. Setting a task's status to done stamps completed_at; an event's outcome stamps outcome_at. A lead's message is stored as the inquiry text but returned by GET only for e-mail imports; source: email_import is reserved. Commission is not part of the API: a sale created through it has none until someone fills it in Estalo.

Idempotency

POST requires an Idempotency-Key header; on PATCH and DELETE it's optional but recommended. Use a new random value (a UUID is fine, up to 128 visible ASCII characters) for each change and reuse it only to retry that change. For 24 hours:

• the same key with the same method, path and body returns the first response again, with Idempotent-Replayed: true, and changes nothing;
• the same key with a different request answers 422 idempotency_key_reused;
• while the first request is still running, 409 idempotency_in_progress: retry in a moment.

Refusals decided after the request was accepted (for example 409 duplicate or 402 plan_limit) are stored and replayed like successes. A 5xx is not stored, so you can retry with the same key.

Concurrent edits

PATCH accepts expected_updated_at: the updated_at you read before deciding on the change. If the record has changed since, the answer is 409 conflict with the current value in details.updated_at; fetch it again and decide again. Without it, the fields you send overwrite whatever is there (other fields are never touched).

Examples

Replace the key and ids with your own. Every POST needs its own Idempotency-Key.

KEY="est_live_xxxxxxxxxxxx_<your-key>"

# Client
curl -s -X POST https://estalo.pl/api/v1/clients \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"first_name":"Anna","last_name":"Nowak","phone":"+48 600 000 000","type":"buyer"}'

curl -s -X PATCH https://estalo.pl/api/v1/clients/42 \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"status":"contacted","expected_updated_at":"2026-11-02T09:15:02.114+00:00"}'

curl -s -X DELETE https://estalo.pl/api/v1/clients/42 -H "Authorization: Bearer $KEY"

# Listing
curl -s -X POST https://estalo.pl/api/v1/properties \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"title":"2 pokoje, Jeżyce","price":649000,"type":"flat","address_city":"Poznań","area":48.5,"rooms":2}'

curl -s -X DELETE https://estalo.pl/api/v1/properties/0f6c2a1e-0000-4000-8000-000000000000 -H "Authorization: Bearer $KEY"

# Sale
curl -s -X POST https://estalo.pl/api/v1/deals \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"title":"Jeżyce 2 pokoje","value":649000,"stage":"new","client_id":42,"property_id":"0f6c2a1e-0000-4000-8000-000000000000"}'

curl -s -X PATCH https://estalo.pl/api/v1/deals/7d1e0c2b-0000-4000-8000-000000000000 \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"stage":"negotiation"}'

# Calendar event
curl -s -X POST https://estalo.pl/api/v1/events \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"title":"Prezentacja","type":"meeting","start_time":"2026-11-05T10:00:00+01:00","end_time":"2026-11-05T11:00:00+01:00","client_id":42}'

# Inquiry (e.g. from your website form)
curl -s -X POST https://estalo.pl/api/v1/leads \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"customer_name":"Jan Kowalski","email":"jan@example.com","message":"Czy oferta jest aktualna?","source":"www"}'

curl -s -X PATCH https://estalo.pl/api/v1/leads/a5d0c3f1-0000-4000-8000-000000000000 \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"status":"contacted"}'

# Task
curl -s -X POST https://estalo.pl/api/v1/tasks \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"title":"Oddzwonić","task_type":"call","due_date":"2026-11-03T09:00:00Z","related_client_id":42}'

curl -s -X PATCH https://estalo.pl/api/v1/tasks/3b9e1d40-0000-4000-8000-000000000000 \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"status":"done"}'

Errors

Every error has the same shape and a stable code:

{ "error": { "code": "insufficient_scope", "message": "…", "request_id": "…" } }

Some errors add param (the parameter, header or field at fault) and details (ids and field names, never another person's data).

Branch on code, not on message. Responses carry Cache-Control: no-store and X-Request-Id.