DEVELOPING

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 two methods

	What it returns
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`

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.

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.

{
  "id": "322337250",
  "propertyCode": "2605257___mapaprop",
  "name": "Lucía",
  "email": "lucia@ejemplo.com",
  "phone": "1156781234",
  "message": "Hola, quería coordinar una visita",
  "date": 1790878040000,
  "portalMessageId": null,
  "portalAdId": 56801168,
  "portalContactId": 49474924,
  "portalActionId": 10
}

Field	What it is
`id`	the lead's identifier. Use it to recognise the lead if it shows up again
`propertyCode`	the listing's code on the portal
`name` · `email` · `phone` · `message`	what the enquirer left. Any of them may come back as `null`: the portal does not require all of them
`date`	the date, in milliseconds since 1970 (epoch)
`portalMessageId` · `portalAdId` · `portalContactId` · `portalActionId`	the portal's internal ids. Useful for cross-referencing against its own reports; you do not need to use them

Our suggestion: identify a lead by the pair portal + id, not by id alone.

We do not generate the id: it is the one each portal issues, in its own numbering. We pass it on exactly as it comes, without adding anything to it. Since each portal numbers independently, two different portals may use the same number for different leads — and the portal field comes back in the response precisely so that you can tell them apart.

We do not store leads

The API does not store leads under any circumstances. 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 your clients' leads on our side.

Two practical consequences, 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 pair portal + id.

The portal's allowance

Every request you make uses one call from the monthly allowance the portal grants that agency.

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`)	with the two methods in this section
The rest	not yet. A request to a portal without this service returns 501, stating which of the two is missing

Each portal decides what it offers: some allow you to query, others notify on their own when an enquiry comes in. As we add each one, this table will say so.

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.