Enquiries for the whole account
GET /property-v1/leads?portal={portal}
Returns the enquiries for every listing of that agency on that portal, in a single call. Each lead
tells you which listing it came from in data.property, so you do not have to ask listing by listing.
How to read the
data.property.code. It is the code the listing lives under on the portal, and for listings you published we build it from your ownpaIdplus a brand suffix:01M416ACSSG7TXX172PDXSQFXF___mapapropis your property01M416ACSSG7TXX172PDXSQFXF. To match it against your records, strip the___mapapropsuffix — do not cut at the first_, since yourpaIdis the one you chose and may contain anything.⚠️ The suffix is not enough to tell whether the listing is yours. The per-account method returns the enquiries for every listing of that agency, and the
___mapapropsuffix is carried by all of those published through Mapaprop — not only yours. The agency may have published listings by another route, and those codes carry the same suffix with an id that is not yours.⇒ Match against your own records, not against the suffix: strip the suffix and look the result up in your properties. If it is not there, that lead belongs to a listing the agency published some other way — it is not an error, and the right thing is to ignore it.
This is the method to use. See why in the introduction.
curl "https://property-api.mapaprop.com/property-v1/leads?portal=zonapropapi&fromDate=20260101" \
-H "Authorization: Bearer $TOKEN" \
-H "x-client-ref: cliente-42"
The parameters
portal | required | zonapropapi · mapapropapi (the Mapaprop source) |
fromDate | from which date. YYYYMMDD, or optionally YYYYMMDD HH:mm:ss | if you omit it, the last 7 days |
toDate | up to which date, same format | no upper bound |
size | how many leads per page | 100, the maximum per request |
maxPages | how many pages we fetch at most | 20 |
The 7-day default is the one for a call with no parameters, so that a request without a date does not try to pull the entire history. It is not a frequency recommendation: you choose the frequency.
The response
{
"portal": "zonaprop",
"from": "20260101",
"leads": [
{
"eventId": "evt_src_322337250",
"event": "lead.created",
"occurredAt": "2026-11-15T03:07:08Z",
"clientRef": "cliente-42",
"source": {
"source": "mapaprop",
"case": "zonaprop",
"subcase": "api",
"ids": { "messageId": null, "adId": "56801168", "contactId": "49474924", "actionId": "10" }
},
"data": {
"questionId": null,
"messageId": "322337250",
"direction": "incoming",
"message": "Hola, quería coordinar una visita",
"contact": { "name": "Lucía", "email": "lucia@ejemplo.com", "phone": "1156781234" },
"customer": null,
"property": { "propertyId": null, "paId": null, "code": "01M416ACSSG7TXX172PDXSQFXF___mapaprop" },
"raw": null
}
}
],
"total": 12,
"quota": { "remaining": 1346, "limit": 1500 }
}
In this source neither of the portal's two ids identifies a message, and it is measured over a
whole account (33 messages from August): source.ids.messageId came back null in 23, and
data.messageId —which never comes back null, and is why we use it to build the eventId— had 31
distinct values for 33 messages, with two genuinely different pairs sharing one.
⇒ Deduplicate with eventId + occurredAt. The two pairs that shared an id were five days apart,
so the date separates them; if two ever reach you with both values equal, compare the content before
discarding.
The lead object, field by field, is in the introduction.
| Field | What it is |
|---|---|
from | the window that was actually used (yours, or the default) |
to | the upper bound of the window that was actually applied. Appears only if you sent toDate |
leads | the leads. It may come back empty, which means there were no enquiries in that window |
total | how many the portal says there are in that window. It can be greater than leads.length — see below |
quota | the balance the portal reported on this call |
The pages, and what each one costs
Leads come from newest to oldest. If your window holds more than fit in one page, we walk the pages
for you up to maxPages.
Each page is one call of your client's monthly allowance. The allowance belongs to the agency and
is shared with publishing, so size and maxPages are cost decisions, not just convenience ones.
On Zonaprop the maximum per page is 100, so maxPages: 20 means up to 2,000 leads and up to 20 calls.
If we hit the ceiling before fetching everything, the response tells you so:
{
"portal": "zonaprop",
"from": "20240101",
"leads": [ "… the ones that fit …" ],
"total": 900,
"truncated": true,
"truncatedReason": "partial_portal_cap",
"detail": "Te devolvemos una parte, los más nuevos primero. Pedí el resto subiendo `maxPaginas` o acotando la ventana con `fromDate`/`toDate` — cada página es una llamada del cupo de la inmobiliaria.",
"pagesFetched": 20,
"quota": { "remaining": 1348, "limit": 1500 }
}
In practice: if you request often — once a day, say — everything fits in one page and you will never lose a lead. The ceiling only shows up when you ask for a very long window, for example on your first sync.
If you paginate on your own instead of using maxPages, you will receive duplicates. Zonaprop's
paging overlaps at the boundary: the next page repeats the last lead of the previous one. We drop it
and tell you so in warnings when it happens.
toDate: with no time, it is the end of that day
?fromDate=20261001&toDate=20261013
If you send toDate without a time, we take it as 20261013 23:59:59 — that is, the 13th is
included. The response's to field gives you back the value that was actually applied, and we tell you:
{
"from": "20261001",
"to": "20261013 23:59:59",
"warnings": [
"Tomamos `toDate` como el final de ese día (`20261013 23:59:59`). Sin la hora, el portal lo lee como las 00:00:00 y habría excluido el día entero. Mandá la hora si querés otro corte."
]
}
The portal reads a date with no time as 00:00:00, so a bare toDate=20261013 would have left out the
whole of the 13th without anything saying so. If you want a different cut-off, send the time
(20261013 18:00:00) and we honour it as is.
Since 2026-10-15 toDate is applied in this listing too. The portal used to ignore it here and we
documented it that way: if you were filtering by date on your side to compensate, you no longer need to.
The Mapaprop account (mapapropapi)
GET /property-v1/leads?portal=mapapropapi
It is not a portal: these are the enquiries that came in through your client's Mapaprop account — their website, their chat, the Mapaprop portal, or a portal that drops them there. You read it with the same endpoint and the response has the same shape, so you do not write a second reading.
The four differences, and they are worth keeping in mind:
| A portal | mapapropapi | |
|---|---|---|
| Allowance | each page is one call of the agency's allowance | 🟢 spends nobody's allowance: the source is our own database |
quota | comes | does not come — sending you a zero would read as "you have none left" |
total | how many the portal says there are in the window | how many we brought you. Counting the window would double the cost of every page, so we do not invent it: to know whether more remain, look at truncated |
| Defaults | size 100 · maxPages 20 | size 50 · maxPages 1 |
⚠️ By default we bring you a single page of 50. If there are more in that window the response carries
truncated: true and a notices saying so. Since paging is free, raise maxPages with confidence — the
only limit is the size of the response.
How you identify the property in this source
With data.property.propertyId, which is the property's id in Mapaprop.
Not with paId or code: those two are yours — you pick the paId when you post through the
API — and they only exist if that property was born through PropertyAPI. The enquiries from this
source arrive at your client's Mapaprop account, and there the property may have been entered by
hand, imported from another system, or come from a portal. In those cases nobody ever picked a
paId, so it travels as null:
"property": { "propertyId": 2617621, "paId": null, "code": null }
If you did publish that property through the API, all three arrive.
📌 And some enquiries are not about any property — someone writing to the agency rather than
about a listing: there the whole block comes as null. Both branches are worth having in your code.
The window has a cap: one year
{ "error": "window_too_wide", "detail": "La ventana no puede ser mayor a un año. Acotá `fromDate`/`toDate` y paginá.", "portal": "mapapropapi" }
A 400. It is the only parameter this source validates differently from the portals.
A malformed request comes back as a 400, not a 502
{ "error": "invalid_request", "detail": "fromDate must be a date, as yyyy-MM-dd", "portal": "mapapropapi" }
The detail carries the reason exactly as the source states it, so you can read it and fix it:
retrying changes nothing. The 502 mapaprop_unavailable is left for what it actually means — that
we couldn't reach Mapaprop — and that one is worth retrying.
📌 The date is accepted in both forms: YYYYMMDD (the one in the table above) and yyyy-MM-dd.
Today it serves YOUR account, not your clients'
{ "error": "no_mapaprop_account", "detail": "Los leads de esta fuente son de una cuenta de Mapaprop, y este token no corresponde a ninguna.", "portal": "mapapropapi" }
A 400, and you want to know it before writing the code: this source resolves the account from your
token, so it works if your token came from a Mapaprop account. If you are a platform whose clients have
a Mapaprop account, what serves you today is the webhook — through it
you do receive your clients' enquiries, without having to request them. It is the same limitation as
branches, and we are going to close it: write to
dev@mapaprop.com if it blocks you.
The errors
| When | What to do | |
|---|---|---|
400 portal_required | ?portal= is missing | send it |
| 403 | you are missing the {portal}:leads scope | ask us to grant it |
409 portal_not_connected | that account is not connected to that portal | connect it |
409 portal_account_unlinked | it was unlinked on the portal's side | it has to be connected again |
429 portal_quota_exhausted | the agency used up its monthly allowance | wait for the following month. The allowance is shared with publishing — see Zonaprop's allowance |
501 leads_not_supported | that portal does not offer this service yet | — |
502 portal_rejected | the portal did not answer or rejected the request | retrying is safe: querying changes nothing |
A deactivated account does not block this request: the leads that already came in belong to your client, and they can still be retrieved.
Before building the call, check which mode that portal supports.
Not all of them offer this service, and this way you find out as data instead of through a 501.