Get ready for the first lead
When your client adds the enquiries permission to their Mapaprop account, the enquiries that arrive in their inbox start reaching you. There is nothing else to activate, no migration to run and no button to press: from one moment to the next they simply start appearing.
This page is what is worth having ready before that moment.
This is the mapapropapi source, the one that is not a portal: these are the enquiries that
come in through your client's website, their chat, the Mapaprop portal, or a portal that drops them
into their inbox. Portal leads keep working exactly as before.
What happens exactly when it is switched on
today nothing from this source reaches you
↓ the permission is added to your client's account
from there every new enquiry reaches you through your webhook, within seconds
Three things worth knowing about that cut:
| It starts with what is new | we do not resend the history. The first one you get is the first one that comes in after the permission |
| Nothing from before is lost | it is in your client's account, and you can request it by account up to a year back |
| Your client still sees everything | the enquiries do not move: they stay in their Mapaprop inbox, and they keep answering from there |
The five things that have to be ready beforehand
1 · The webhook registered, and the secret stored
It is declared once with PUT …/webhooks/lead. That is where the
secret we sign every delivery with comes from.
The secret is returned ONCE. Store it at that moment: we cannot show it again, and without it you cannot verify that the deliveries are ours.
2 · An endpoint that answers fast and stores
Store the raw envelope and answer 2xx; process it afterwards. An endpoint that validates,
enriches and writes to three systems before answering is an endpoint that goes down more often than
the one that only stores — and you get three attempts, about 2 minutes apart.
🟢 And here there is a safety net that portal leads do not have: if your endpoint was down, the enquiries from this source still exist and you can request them again by account. You do not depend on the delivery alone.
3 · Deduplicate by eventId
That is the key, and it comes from the fact, not from the attempt: if we re-deliver the same
enquiry, it arrives with the same eventId. Store it and you are done.
4 · Accept an enquiry without a property
🔴 16.9 % of enquiries are not about any listing. Someone writes to ask about an area, about a
budget, about availability in general. They arrive with data.property as null.
If your system only knows how to store an enquiry attached to a property, those get lost without anything failing. It is the most expensive thing to find out late. You need an inbox for the ones that belong to no listing.
5 · Stitch together the messages of the same thread
An enquiry can have several messages. Two leads with the same data.questionId are the same
conversation, and lead.event tells you what each one is:
lead.event | What to do |
|---|---|
lead.created | open the record: the conversation was born |
lead.message | add it to the thread that already exists, do not open another |
Without this, your user sees three contacts where there is one person writing three times.
Day 1: what to look at
- Did anything arrive? Request the enquiries of the account
with
?portal=mapapropapi. It is free: this source spends no portal's allowance. - Did it arrive through the webhook and is it also in the
GET? It has to be the sameeventId. If it is, the chain is complete. - Does the
GETbring enquiries and the webhook brought you none? Then the problem is in the delivery, not in the origin: check that your endpoint answers2xxand that the registered URL is the one you think it is.
Before writing to us, that order saves half the cases: the GET tells you whether the enquiry
exists on our side. It separates "it did not come in" from "we could not deliver it to you",
which are two different problems with two different solutions.
If something does not work
When something does not work has the full route. What is worth repeating here:
Support goes up the chain: your client writes to you, and you write to us. Send us the
reference from the error and the clientRef: with those we find your exact call.
What does NOT change
- Your client keeps working the same way. The enquiries keep arriving in their Mapaprop inbox and they answer from there. This does not change their screen or move anything around.
- Portal leads stay as they were. This source is added; it replaces nothing.
- What your client contracts with each portal —their account, their plan— is theirs and direct, as always.
See also
- The lead object — the shape, field by field
- The enquiries of a whole account — including the
mapapropapisource - Webhooks — declaring where we deliver
- Receiving enquiries — the full flow
- API changes — the lead's shape changed on 20 November 2026