Leads
When someone sees one of your client's listings on a portal and leaves an enquiry, that is a lead: their name, their email, their phone number and whatever they wrote.
This API delivers them to you. You decide when to request them — there is nothing to wait for and no schedule to follow.
The methods
| What it returns | Scope | |
|---|---|---|
| Enquiries for the whole account | all of them for that agency, across all of its listings | {portal}:leads |
| Enquiries for a single property | only those for that listing | {portal}:leads |
| Which mode each portal supports | no enquiries: it tells you whether on that portal they are requested or arrive on their own | property-api-catalog |
The third one carries a different scope on purpose. The first two return personal data of the interested parties, so they are granted portal by portal. The third one returns no enquiry at all — it only says how each portal works — and it speaks about all of them at once, so it uses the catalog scope, the same one used for zones and attributes.
Start with the whole-account method. Every lead tells you which listing it came from, so a single call brings you everything: that is the normal path. The single-property method exists for when you want to look at just one — the detail view of a listing in your panel — and pulling the rest makes no sense.
And there is a source that is not a portal: mapapropapi. These are the enquiries that arrive in
your client's Mapaprop account — through their website, their chat, or a portal that drops them there.
They are requested the same way (?portal=mapapropapi) and have an advantage: they spend no
portal's allowance, because there is no portal in between. You can page without counting calls.
What they do have is a window limit: one year back per request.
Our suggestion: do not walk through your listings one by one. With 500 listings and one enquiry per day that would be 15,000 calls a month; with the whole-account method, the same thing is ~30. On Zonaprop, whose usual allowance is 1,500 calls per month per agency (see Zonaprop's allowance), the first does not fit and the second uses 2 %.
The allowance is set by each portal, so the number varies from portal to portal. What does not vary is the ratio: one call per account will always cost far less than one per listing.
The lead object
It is the same in both methods, and the same one the webhook delivers. One shape to read, no matter where the enquiry came from or which door you received it through.
{
"eventId": "evt_1622087_c",
"event": "lead.created",
"occurredAt": "2026-11-15T03:07:08Z",
"clientRef": "cliente-42",
"source": {
"source": "mapaprop",
"case": "zonaprop",
"subcase": "api",
"ids": {
"messageId": "322337250",
"adId": "56801168",
"contactId": "49474924",
"actionId": "10"
}
},
"data": {
"questionId": "1622087",
"messageId": null,
"direction": "incoming",
"message": "Hola, quería coordinar una visita",
"contact": { "name": "Lucía", "email": "lucia@ejemplo.com", "phone": "1156781234" },
"customer": { "customerId": 441 },
"property": { "propertyId": 2610019, "paId": null, "code": null },
"raw": null
}
}
The envelope
| Field | What it is |
|---|---|
eventId | the identifier of this event. It is stable: if we re-deliver it, it arrives with the same one. This is what you deduplicate with |
event | lead.created when the conversation is born · lead.message when a new message arrives in one that already existed |
occurredAt | when it happened, in ISO-8601 UTC. It is the origin's time, not ours |
clientRef | which of your clients it belongs to |
source | where it came from — see below |
Where it came from
| Field | What it is |
|---|---|
source.case | zonaprop, argenprop, mercadolibre, cabaprop, website, chat-ai, portal-mapaprop, network-search, network-site, feed |
source.subcase | the channel within that case when there is more than one (api or xml on Zonaprop and Argenprop). null when the case has only one |
source.ids | the ids that origin uses for the same message. Useful for cross-referencing against its reports; you do not need to use them |
The enquiry
| Field | What it is |
|---|---|
questionId | the conversation. Two messages with the same questionId are the same thread — this is what lets you stitch them together instead of creating two enquiries |
messageId | the message within that conversation. It travels as null in a lead.created, because that event is the birth |
direction | always incoming when it reaches you: we only send you what came in |
message | what the enquirer wrote |
contact | name, email, phone. Any of them may come back as null: not every origin requires all of them |
customer | the Mapaprop account, when that client has one |
property | see below |
raw | reserved. It travels as null today |
The property, and what it means when it does not come
| Field | What it is |
|---|---|
property.propertyId | the property's id in Mapaprop |
property.code | the code the listing lives under on the portal |
property.paId | your id. It travels as null today — see below |
🔴 Which id reaches you depends on the source, and the difference matters:
propertyId | code | paId | |
|---|---|---|---|
A portal (zonapropapi) | — | ✅ the listing's code | — |
The Mapaprop account (mapapropapi) | ✅ | — | — |
⇒ Do not write your matching against a single field. For a portal you match on code
(how to read it); for the Mapaprop account, on propertyId,
which is the same id the property's GET returns.
paId is in the contract and today is not filled in by either of them: you will see it start to
arrive without having to change anything, and in the meantime it is of no use for matching.
property: null means they did not ask about any, never that we failed to resolve it. It happens
often: 16.9 % of enquiries are not about one particular listing, and on MercadoLibre they are
34 %. They are just as valid — someone writing to ask about an area, for instance — and you have
to be able to receive them.
To recognise a lead: use eventId
The eventId comes from the fact, not from the attempt. If a re-delivery brings you the same
enquiry twice, both arrive with the same eventId — so storing it is enough to avoid duplicates.
The exception: leads that never pass through a Mapaprop account. There is no conversation of ours
to name there, so the eventId is built from the id the origin sends and arrives with the prefix
evt_src_. And on Zonaprop that id, measured, is not unique: the same person writing twice about
the same listing on different days arrives with the same number and a different occurredAt.
⇒ If you receive leads of that kind, add occurredAt to the key. You recognise them because the
eventId starts with evt_src_ and questionId comes back null.
This shape replaced the previous one on 20 November 2026. The old one was flat (id,
propertyCode, name…). The details of the change and the field-by-field equivalence are in
API changes.
What is stored and what is not
The API does not keep the portals' leads. We ask the portal, we hand you the answer, and nothing stays with us: not the name, not the email, not the phone number, not the message. There is no database of portal leads on our side.
The mapapropapi source is different, and the difference is one of origin. Those enquiries were
born in your client's Mapaprop account — through their site, their chat or the Mapaprop portal —
so they live in their inbox because that is where they came in: we do not store them in order to hand
them to you. They are your client's data, in their own account, and they keep seeing and answering
them from Mapaprop.
⇒ The practical consequence is a good one: those you can always request again, up to a year back.
Two practical consequences of the above, worth keeping in mind as you design your integration:
- Storing them is your job. If you do not persist them when you receive them, they are gone — we cannot look them up again in a history of ours, because no such history exists.
- You can request the same thing as many times as you like. We do not keep track of what we already delivered, so requesting a window you already requested returns the same leads. This is deliberate: if your system loses one, you can fetch it again. You are the one who decides what is new, using the key above.
The portal's allowance
Every request to a portal uses one call from the monthly allowance that portal grants the agency.
🟢 mapapropapi uses nobody's allowance — there is no portal in between, so there you can page
without counting calls and this section does not apply to you.
Each portal has its own allowance, its own rules and its own page. Today the only one with this service built is Zonaprop; as we add others, each one will contribute its own.
| Portal | The allowance | Where the detail is |
|---|---|---|
| Zonaprop | 1,500 calls per month per agency (usual allowance) | Monthly allowance and limits |
The allowance is shared with publishing. On Zonaprop, publishing a listing, checking its status and fetching these enquiries all draw from the same allowance. If you exhaust it fetching leads, your client cannot publish until the following month. What consumes it and what does not, operation by operation, is in Monthly allowance and limits.
Every response tells you where the balance stands:
"quota": { "remaining": 1346, "limit": 1500 }
That number is the one the portal reported on that call, not a live value. If the agency also publishes on the portal outside your system, the real balance drops without either of us finding out.
A reference for choosing your frequency, using the whole-account method:
| How often you request | Calls per month | Of the allowance |
|---|---|---|
| once a day | ~30 | 2 % |
| every 6 hours | ~120 | 8 % |
| once an hour | ~720 | 48 % |
Which portals
| Portal | How enquiries are obtained today |
|---|---|
Zonaprop (zonapropapi) | you go and fetch them, with the two methods in this section |
Argenprop (argenpropapi) | they reach you, at the URL you declare in Webhooks. It does not have the methods in this section: a request here returns 501 |
The Mapaprop account (mapapropapi) | both: you fetch them with the whole-account method, and they also reach you by webhook |
| The rest | not yet, in neither of the two ways |
They are not two levels of the same thing: they are two different mechanisms, and a portal can have
one and not the other. If you go and fetch the enquiries of a portal that only pushes, the 501 tells
you which of the two services is missing — but asking costs nothing and is better than finding out that
way: Capabilities answers it for every portal at once, and it
is the same data our own code uses.
The permission
Both methods require the scope {portal}:leads — for example zonapropapi:leads.
Having {portal}:publish is not enough. They are deliberately separate permissions: fetching leads
means accessing third parties' personal data — the people who enquired about a listing — and that is
not granted together with publishing. If you need both, you will be granted both scopes.