Property Finder

Every enquiry on your Property Finder listings — WhatsApp, email, or call — can land in Whispyr within seconds, deduplicated against the people you already know, assigned to the right agent, and carrying the context of what the person actually enquired about. This guide walks you through the one-time setup, end to end.

Setup is shorter than Meta's. You create one API key inside Property Finder and paste it into Whispyr. That is the whole handshake. You never paste a callback URL or a verify token into Property Finder — Whispyr registers its own webhook subscription with Property Finder on your behalf the moment you connect.

Before you start

Check that you have each of these ready. If you miss one, Property Finder will stop you later in the flow.

• A PF Expert 2.0 account for your brokerage. Enterprise API access is free — Property Finder does not charge for it.
• Decision Maker permissions in PF Expert. Property Finder only lets a Decision Maker generate API keys. If you are not one, ask whoever administers your PF Expert account to either do Step 1 for you or grant you the role.
• Headroom for another key: Property Finder caps you at 3 active API keys at a time. If you are already at 3, disable one you no longer use (see Troubleshooting).
• A Whispyr account with an admin role — Admin, Umbrella Admin, or Franchise Admin. Only those roles can see Settings → Integrations → Property Finder.
• 10 to 15 minutes. You will switch between two browser tabs, one on PF Expert and one on Whispyr.

Note: decide now whether you want the "Honor the listing agent" assignment mode (Step 3). Property Finder cannot change the scopes on an API key after it is created — if you skip the users:read scope in Step 1 and later want that mode, you have to create a brand-new key and reconnect. It costs nothing to include it, so if you are unsure, include it.

What you will do

You will create one Enterprise API key inside PF Expert with the right scopes, paste that key and secret into Whispyr, and pick how Property Finder leads get assigned. When you save the credentials, Whispyr validates them against Property Finder, confirms it can read your leads, and subscribes itself to your lead events automatically. From that point on, every new Property Finder enquiry appears in Whispyr as a lead.

Step 1. Create an Enterprise API key in PF Expert

1. Log in to PF Expert and open Developer Resources → API Credentials in the left sidebar.

   

2. The API Credentials page lists your existing keys and, at the top, how many you have used (Total API Keys and Active API Keys). Click New API Key in the top right.

   

3. The Create new API Key dialog opens. Fill in:

   • Name — anything that identifies it later, for example Whispyr.
   • Expiry period — required. Property Finder allows up to 365 days. Pick the longest period you are comfortable with; when the key eventually expires, Whispyr will alert you and you reconnect with a fresh one.
   

4. Scroll down to Scopes. Each resource is a group of radio buttons — none, read, or full_access. Set:

   • Leads → leads:read. This is required. Without it, Whispyr cannot read your leads and the connection will be refused.
   • Users → users:read. Only needed if you want the Honor the listing agent assignment mode (Step 3). Harmless to include either way.

   Leave every other optional scope at none. Whispyr does not read your listings, credits, or statistics.

   

   Note: the scopes Property Finder grants by default — including Webhooks (webhooks:full_access) — are already enabled and cannot be turned off. That default is what lets Whispyr register its own lead webhook for you, which is why you never paste a callback URL into Property Finder.

5. Tick I agree with the API Access Terms, then click Create Key.

   

6. Your new key appears in the API Keys table with an Active status. Copy the API Key and the API Secret from its row (the secret is masked until you reveal it). Keep both on your clipboard — you paste them into Whispyr next.

Step 2. Connect Property Finder in Whispyr

In your Whispyr tab, go to Settings → Integrations → Property Finder.

If your organization uses franchises and you are an Umbrella Admin, you will see an Umbrella / Franchises toggle at the top. Each scope holds its own Property Finder connection:

• Umbrella — the umbrella organization's own connection.
• Franchises — pick a franchise from the dropdown to manage that franchise's connection.

A franchise's leads arrive on that franchise's own key, so Whispyr always knows which franchise an enquiry belongs to without any extra mapping. If you are a Franchise Admin, or your organization does not use franchises, there is no toggle — you manage your single connection directly.

1. In the Connect Property Finder card, paste the API key and the API secret from Step 1.
2. Click Connect.

Saving is not a blind write. Whispyr validates the credentials against Property Finder before it stores anything:

1. It exchanges your key and secret for an access token, proving the credentials are real.
2. It confirms the key can actually read leads (the leads:read scope).
3. It subscribes itself to your lead.created and lead.assigned events, registering its own callback URL and generating a signing secret so it can verify that every future delivery genuinely came from Property Finder.
4. Only then does it encrypt and store the key and secret.

If any of those steps fails, nothing is saved and the reason appears inline. See Troubleshooting below.

On success the card flips to Property Finder connection with a green Connected badge. The key and secret are shown as masked rows from then on — Whispyr encrypts both at rest and there is no reveal button, by design. If you need the originals, they live in PF Expert.

Note: Whispyr subscribes to lead.created and lead.assigned on purpose. Off-plan and Primary Plus project leads never fire lead.created on Property Finder's side — they only ever arrive as lead.assigned. Subscribing to both is what stops your project enquiries from silently going missing.

Step 3. Choose how Property Finder leads are assigned

Once a connection exists, a Lead assignment card appears. The choice is per connection, so your umbrella and each franchise can decide independently.

Automatic assignment (the default)

Whispyr distributes each Property Finder lead using your normal automatic-assignment rules — the same path Meta and Custom API leads already take. Nothing else to configure.

Honor the listing agent

Each new lead goes to the Whispyr user mapped to the Property Finder agent whose listing produced the enquiry. This mode needs the users:read scope on your API key.

When you switch to it, a Listing-agent mapping card appears below. Whispyr pulls your Property Finder agent directory and, for each agent, suggests the Whispyr user with a matching email address. Suggestions are never applied silently — you click Use suggestion to accept one, or pick a different user from the dropdown. Use Clear to unmap an agent.

Note: an unmapped agent is never a dropped lead. If a Property Finder agent has no confirmed mapping — or the mapped user has since been deactivated or moved out of the connection's scope — that lead quietly falls back to normal automatic assignment.

What happens when a lead arrives

A new Property Finder enquiry becomes a Whispyr lead within seconds. Whispyr:

• Deduplicates the person. A phone number you already know resolves to the same person, and the enquiry is appended as a new touchpoint rather than creating a duplicate contact. Two genuine enquiries from the same person stay two separate touchpoints.

• Attaches the enquiry context as a system note on the lead, so the agent working it sees what was actually asked about without digging:

  **Property Finder Enquiry**
  
  - Channel: whatsapp
  - Enquiry type: listing
  - Status: delivered
  - Listing reference: <the PF listing reference>
  - Property Finder agent: <the PF agent id>

  Only the fields Property Finder populated for that enquiry appear — a call has no response link, a listing enquiry has no project id.

• Handles every channel on one connection. WhatsApp, email, and call enquiries all arrive through the same webhook and are distinguished by the Channel line above. You do not need Property Finder's separate WhatsApp product for leads to reach Whispyr.

One enquiry that cannot become a lead is one that arrives with no phone number at all — a Whispyr lead is identified by its phone. Those deliveries are not silently dropped: they are recorded in Webhook logs as Failed, with the reason spelled out, so you can see exactly what came in.

The safety net

Webhooks occasionally get lost in transit. Whispyr does not rely on them alone: every hour, it sweeps the last 6 hours of leads from Property Finder for each connection and ingests anything the webhook never delivered. A lead younger than 15 minutes is left alone — that is the live webhook's window to deliver it normally.

Because leads are deduplicated on Property Finder's own lead id, a lead that already arrived is never ingested twice, so the sweeps are free to overlap. In practice each lead gets about six chances to land.

You can see every inbound delivery, per attempt, in Webhook logs — including which were rescued by the hourly sweep rather than delivered live. A delivery that failed can be retried from there, without Property Finder having to resend anything.

Troubleshooting

"Property Finder rejected these credentials. Check the API key and secret and try again."

The key or the secret is wrong, or the key has been disabled or has expired in PF Expert. Re-copy both from Developer Resources → API Credentials — it is easy to grab one and not the other, or to pick up a stray space. Confirm the key's status still reads Active in the table.

"These credentials are valid but do not have lead access."

The key is real, but it was created without the leads:read scope. Property Finder cannot add a scope to an existing key. Create a new key with leads:read selected (Step 1), then paste the new key and secret into Whispyr.

"Could not reach Property Finder to validate these credentials."

A transient network or Property Finder-side problem, not a mistake on your part. Nothing was saved. Try again in a moment.

"These credentials are valid, but Property Finder rejected the webhook setup for lead delivery."

Your credentials are fine, but Property Finder refused the webhook subscription. Nothing was saved. Try again in a moment; if it persists, contact Property Finder's integration support at integration.support@propertyfinder.ae.

Honor-listing-agent mode will not turn on

The error names the cause: the key lacks the users:read scope, and Property Finder cannot add scopes to an existing key. Create a new key with both leads:read and users:read (Step 1), reconnect with it, then switch the mode on.

The agent list is hidden on the mapping screen

An amber banner saying your key cannot read Property Finder agents means the same thing: the key is missing users:read. Your existing confirmed mappings still work — only the live agent directory and its fresh suggestions are hidden. Re-mint the key with users:read and reconnect to get them back.

A grey banner instead means Whispyr simply could not reach Property Finder at that moment. Existing mappings still apply; try again shortly.

"Property Finder needs to be reconnected"

Whispyr discovers a dead credential the moment it tries to use one — it does not track your key's expiry date in advance. When Property Finder starts rejecting the stored key, the connection flips to Needs reconnect, new leads stop arriving, and Whispyr alerts every admin on that connection by in-app notification, email, and push. The alert links straight to the connection that broke.

Two causes, and the banner tells you which one:

• The key was rejected. It expired, was disabled, or was deleted in PF Expert. Create a fresh key (Step 1) and save it on the connection card.
• Lead access was removed. The key still works but no longer carries leads:read. Create a fresh key with leads:read and save it.

Reconnecting replaces the credential in place. No lead history is lost. While a connection is in this state it is skipped by the hourly sweep too, so reconnect promptly: once you do, the connection re-enrols and the next sweep backfills whatever arrived in the previous 6 hours. Leads older than that window are not recovered automatically.

A delivery shows as Failed in Webhook logs

Open the row in Webhook logs to see the reason. The common one is an enquiry that arrived without a phone number — Whispyr identifies a lead by phone, so there is nothing to create. That is a Property Finder-side data issue, not a misconfiguration; the raw delivery is kept so you can see the enquirer's details and follow up by hand.

If the reason indicates a processing problem rather than missing data, use the Retry action on the row. Whispyr reprocesses the stored delivery — Property Finder does not need to resend it.

You are at Property Finder's 3-key limit

Open Developer Resources → API Credentials, click the three-dot menu on a key you no longer use, and choose Disable. Do not disable the key Whispyr is currently using unless you are replacing it.

Frequently asked questions

Do I need Property Finder to approve Whispyr as a partner?

No. Whispyr connects using your own Enterprise API key, which you generate yourself in PF Expert. There is no partner review, no security assessment, and no waiting on Property Finder to switch anything on.

Does the Enterprise API cost anything?

No. Property Finder provides Enterprise API access free of charge.

Do I need to give Property Finder a webhook URL?

No — and this is the main way this setup differs from Meta's. Property Finder lets an API key manage its own webhook subscriptions, so Whispyr registers its callback URL and signing secret for you the moment you connect. There is nothing to paste back into Property Finder.

Can I change the scopes on a key I already made?

No. Property Finder freezes an API key's scopes at creation. To change them you create a new key and reconnect with it. This is why Step 1 asks you to decide about users:read up front.

Does Whispyr ever see my API secret in plain text?

No. The API key, the API secret, and the webhook signing secret are all encrypted at rest before they are written to the database. Whispyr decrypts them only in memory, only at the moment it needs to call Property Finder or verify an incoming delivery. There is no reveal button in the UI — once saved, the values never come back out.

Can each franchise use its own Property Finder account?

Yes. Every scope — the umbrella and each franchise — holds its own independent connection, its own API key, and its own assignment mode. Because a franchise's leads arrive on that franchise's own key, Whispyr routes them to the right franchise without any additional configuration.

What does Whispyr do with my listings?

Nothing. This integration is inbound leads only. Whispyr does not create, edit, publish, or read your Property Finder listings, and it does not touch your credits. The only scope it requires is leads:read.

Will I see Property Finder status changes on the lead?

Not today. Whispyr captures the enquiry's status at the moment it arrives and records it on the lead. Later status changes on Property Finder's side (a call being answered, a message being read) are not mirrored back onto the Whispyr lead.

Screenshots of PF Expert are Property Finder's own, from their Enterprise API documentation, current as of 2026-07-12. If a screen looks different from yours, the underlying step is the same.