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 lead's id
4 · 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 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.
3 · Deduplicating: not optional
Every enquiry comes with an identifier, and that is your deduplication key. Store it.
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 · 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.
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
- Publication — the portals and what changes on each