BETA

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 returnsScope
Enquiries for the whole accountall of them for that agency, across all of its listings{portal}:leads
Enquiries for a single propertyonly those for that listing{portal}:leads
Which mode each portal supportsno enquiries: it tells you whether on that portal they are requested or arrive on their ownproperty-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

FieldWhat it is
eventIdthe identifier of this event. It is stable: if we re-deliver it, it arrives with the same one. This is what you deduplicate with
eventlead.created when the conversation is born · lead.message when a new message arrives in one that already existed
occurredAtwhen it happened, in ISO-8601 UTC. It is the origin's time, not ours
clientRefwhich of your clients it belongs to
sourcewhere it came from — see below

Where it came from

FieldWhat it is
source.casezonaprop, argenprop, mercadolibre, cabaprop, website, chat-ai, portal-mapaprop, network-search, network-site, feed
source.subcasethe 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.idsthe ids that origin uses for the same message. Useful for cross-referencing against its reports; you do not need to use them

The enquiry

FieldWhat it is
questionIdthe conversation. Two messages with the same questionId are the same thread — this is what lets you stitch them together instead of creating two enquiries
messageIdthe message within that conversation. It travels as null in a lead.created, because that event is the birth
directionalways incoming when it reaches you: we only send you what came in
messagewhat the enquirer wrote
contactname, email, phone. Any of them may come back as null: not every origin requires all of them
customerthe Mapaprop account, when that client has one
propertysee below
rawreserved. It travels as null today

The property, and what it means when it does not come

FieldWhat it is
property.propertyIdthe property's id in Mapaprop
property.codethe code the listing lives under on the portal
property.paIdyour id. It travels as null today — see below

🔴 Which id reaches you depends on the source, and the difference matters:

propertyIdcodepaId
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:

  1. 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.
  2. 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.

PortalThe allowanceWhere the detail is
Zonaprop1,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 requestCalls per monthOf the allowance
once a day~302 %
every 6 hours~1208 %
once an hour~72048 %

Which portals

PortalHow 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 restnot 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.