Receiving enquiries
Enquiries (or leads) are what a person interested in a listing leaves behind. It is the only flow in the API where the direction is reversed: in all the others you send something and we take it to the portal; here the data is born outside and has to reach you.
That changes the design: it is not about what order to call things in, but about who triggers and how often.
The path
1 · how does it work on this portal? GET …/leads/capabilities free. ASK THIS FIRST
2 · depending on the answer:
· you request them GET …/leads (each call costs)
· they arrive on their own ← your endpoint + verifying our signature
3 · deduplicate by the `eventId`
4 · split the batch per destination on your side, with no new calls
5 · reply to the person through your own channel, not through here
1 · First ask how it works on that portal
…/leads/capabilities is free and it is the step most
people skip. There are three modes and you do not choose them: the portal defines them.
| Mode | Who triggers | What you need to have |
|---|---|---|
| you ask | your integration, whenever you want | nothing: one call |
| the portal notifies | the portal | an endpoint of yours, and verifying our signature |
| we push to you | us | the same: your endpoint and the signature |
Why you ask instead of assuming: if you build your integration to request enquiries and that portal only pushes them, you will not receive anything — and you will not see any error, because requesting something that is not there returns an empty list perfectly normally.
⚠️ An empty list does not mean "there are no enquiries": it can mean "on this portal they are not
requested that way". Those are two different things and only capabilities tells them apart.
2 · Fetching them, if on that portal they are requested
There are two scopes and the difference is one of cost, not of content:
| When | |
|---|---|
| The whole account | the normal path: one call brings you those of all that client's listings |
| One property | when you already know which listing you care about |
🔴 Do not walk through your properties requesting each one's enquiries. With 300 listings that is 300 calls from your client's allowance to fetch what one call fetches. It is the most expensive mistake in this flow.
If they arrive on their own
You need an endpoint of your own, and you need to declare it to us once with
PUT …/webhooks/lead. That is where the secret we sign every
delivery with comes from — it is returned only once, so save it at that moment.
After that, verify our signature before trusting the content: that is what distinguishes a notification from us from anyone who discovers your URL. And it is worth having your endpoint answer fast and store: processing afterwards is more robust than processing while you answer.
If you need one specific client's enquiries to go to a different URL, you declare it the same way but
with their x-client-ref.
3 · Deduplicating: not optional
Every enquiry comes with an eventId, and that is your deduplication key. Store it.
It comes from the fact, not from the attempt: a re-delivery of the same enquiry arrives with the
same value, so storing it is enough. The only exception is measured and belongs to Zonaprop — the
origin's id is not unique there — and it is solved by adding occurredAt to the key: the details are
in the lead object.
You need it because the same enquiry can reach you twice for perfectly normal reasons: you requested a range that overlaps the previous one, you retried, or the portal notified you and you also asked. None of those is an error, and without deduplication they turn into a duplicate contact for your user.
4 · Splitting the batch: request per account, separate per listing
The two previous steps leave you with a batch for the whole agency, and that is where the best practice of this flow lies: you bring it together and you split it on your side.
Almost every enquiry tells you which listing it came from, so splitting it needs no further call — it is an operation in your own database. Separate them as they arrive and send each one where it has to be read: the listing's inbox, the branch's, the inbox of the agent who took it on.
🔴 And your split needs an inbox for the ones that belong to no listing. 16.9 % of enquiries are
not about one particular property — on MercadoLibre, 34 %: someone writes to ask about an area,
about a budget, about availability in general. They arrive with data.property as null, they are just
as valid, and a split that only knows how to route by listing discards them without anything
failing. It is the most silent defect of this flow.
Why the splitting belongs on your side and not on ours: the per-account call costs one and brings everything; asking listing by listing to have them already separated costs one per listing and brings exactly the same thing. With 300 listings, that is the difference between 1 call and 300 from your client's quota, for the same data. Grouping is free; calls are not.
⚠️ The batch includes listings that are not yours, and that is normal. It comes with the enquiries of every listing that agency has on that portal, including the ones it published by another route. The ones that do not match any of your properties are not an error: they are the agency's, and the right thing to do is ignore them. How to match each enquiry with your property is covered in the enquiries of the whole account.
🔴 And do not use the splitting as your ownership criterion. An enquiry landing in one of your inboxes has to be the consequence of having matched it against your own database — never of having assumed that everything that arrived in the batch is yours.
4-bis · Stitch together the messages of the same thread
An enquiry can have several messages: the interested person writes, and then writes again. If you open a new record for each message, your user sees three contacts where there is one conversation.
When the lead carries data.questionId, that is the conversation: two leads with the same value are
the same thread. And lead.event tells you what each one is:
lead.event | What it is |
|---|---|
lead.created | the conversation was born — this is where you open the record |
lead.message | a new message of one that already existed — this is where you add to the thread |
questionId comes when the enquiry went through your client's Mapaprop account
(portal: "mapapropapi"). A lead that goes straight from the portal to your system has no thread to
name and carries it as null: there each enquiry is one, and it is right to treat it that way.
5 · Replying to the person
Through your own channel. This API brings you the enquiry; the conversation with the person does not go through here.
Which cadence to choose
If on that portal enquiries are requested, the cadence is yours to decide and your client pays for it:
- Request by account, not by property (one call instead of N).
- Pick a frequency that matches how the data is actually used. A lead that gets looked at each morning does not need to be polled every five minutes.
- If the portal pushes, there is no need to ask as well: you would be paying for something that already reached you.
- 🟢
mapapropapiis the exception to all of this: it spends nobody's allowance, so cadence there is not a cost decision. The point above still applies: if it already reaches you by webhook, requesting it as well only gives you duplicate work.
What can come back empty and is not an error
- Blank fields from the person. The portal does not require every detail; an enquiry can arrive with no phone number or no name. Your system has to accept it all the same.
- An empty list. It can be that there are no new enquiries, or that that portal does not work this way (step 1).
Related
- Leads — the methods and the object we return
- Which mode each portal supports — step 1
- Webhooks — declaring which URL of yours we deliver to
- Publication — the portals and what changes on each