Getting Started

Are you a web developer? Click here to jump straight into the WebToProspect code repository.

WebToProspect can be called anonymously or with a valid Force.com Session ID. To use the latter, you must authenticate through standard Force.com authentication methods first.

---

Anonymous Call

To call W2P anonymously, follow the instructions below:

1. Enable Webservices

• First,  enables webservices for your Propertybase account.

Next we need double check Object Settings for webservices.

• In the Setup menu, click Sites.

• Click the site label for the site that you created when you enabled webservices.

• Near the top of the page, click Public Access Settings.

• Click Object Settings.

• In this list of Objects, click Contacts.
• Next, click the Edit button.

• On the next page, enable all available Object Permissions. (Read, Create and Edit.)

• On the same page, enable Field Permissions for fields that your webservice should have access to.

• Next repeat the process above and grant object permissions for both Listing and Inquiry objects.

2. Locate End Point

• After performing the steps above, your webservice end point will be immediately available at:
• https://yoursitename.secure.force.com/services/apexrest/pba/webtoprospect/v1/

3. Add Security Token

Lastly, generate a security token and save it as a Propertybase setting.

Setting Name/Key	Setting Value
webserviceWebToProspect_token	Generate a unique token using a hash generator.

Note: Type a word into the hash generator mentioned above. Do not leave the string box empty.

---

Session ID Call

If you prefer to use normal authentication, you must generate a session ID before you can call the webservice. This can be done using several methods, including OAuth or calling the login method of the SOAP API.

Note: A pure REST based login will be available in a future Force.com platform release.

Once you've generated your session ID, add it to the header of all your REST calls. Normally a session ID is only valid for two hours. It's recommended to cache this ID locally to avoid the need to login for each call - at least until your session expires.

Example Call with Curl

curl -H "Authorization: Bearer sessionId" -H "Content-Type: application/json" -d @json.txt "https://instance.salesforce.com/services/apexrest/pba/webtoprospect/v1/"

In the example call above, replace the following:

• Replace sessionId with the <sessionId> element that you received from the the login response.
• Replace instance with your <serverUrl> element. (To locate this, login to Propertybase and reference the first part of the URL. It's located after the https://. E.g. na13, eu2, as1, etc.)
• json.txt should be a text file with a valid JSON string as described in the "JSON Structure" tab on this page.

JSON Structure

Below is an example JSON string, broken down into each component.

{
     "prospect": {
         "token" : "abc123",
         "contact": {
           "FirstName": "Max",
           "LastName": "Mayer",
           "Phone": "+49 89 123456",
           "MobilePhone": "+49.110.5041975",
           "Email": "max@example.com"
            },
         "request": {
           "pba__Bedrooms_pb_min__c": 2
         },
         "favoriteListings": [
           "a09E000000BRg1nIAD",
           "a09E000000BKh2oBAK"
               ],
         "contactFields": [
           "Email",
           "Lastname",
           "Phone"
         ],
         "requestFields": [
           "pba__Bedrooms_pb_min__c",
           "pba__FullBathrooms_pb_min__c"
         ],
         "ownerFields": [
           "Firstname",
           "Lastname",
           "Email"
         ]
      } 
}

Security Verification

• token: is your webserviceWebToProspect_token specified as a setting in Propertybase. Note: This is only required if you call it as an anonymous webservice (see "Anonymous Call" tab.)

Form Data

• contact: is data written to the Contact record. This is a name/value map, where the name is the Contact API field name in Propertybase and the value is the data coming from the web form.
• request: is data written to the Inquiry record. This is a name/value map, where the name is the Inquiry API field name in Propertybase and the value is the data coming from the web form.

Note: If you include requestFromListing, the system will first create the Inquiry from your Listing data and then apply your specific values. This could potentially override the values that were previously calculated. (See below.) Update April 2021: Salesforce has deprecated a functionality needed for this to work. Please discontinue the use of "RequestFromListing". Use favoriteListings instead and enhance the inquiry with automations once it is in your system.

Additional Data (Optional)

• requestFromListing: if you include the ID of a Listing here, the system will try to create an Inquiry based on the data in the supplied Listing record. E.g. price range around the listing price, number of bedrooms, number of bathrooms, etc. Update April 2021: Salesforce has deprecated a functionality needed for this to work. Please discontinue the use of "RequestFromListing". Use favoriteListings instead and enhance the inquiry with automations once it is in your system.
• favoriteListings: this is a list of Listing IDs. For each ID supplied, the system will create a Linked Listing and attach it to the new Inquiry. If you create your Inquiry based on a Listing, make sure to include the Listing ID in this list as well.

Returned Data

• contactFields: this is a list of field names which that will be returned after your lead data has been successfully written to Propertybase.

• requestFields: this is a list of field names which that will be returned after your lead data has been successfully written to Propertybase.

• ownerFields: this is a list of field names, coming from the User record who owns the new Inquiry, that will be returned after your lead data has been successfully written to Propertybase.

Other Tips

• date fields: this can be used to pass in a specific date into the date field in Propertybase. (Use format: yyyy-mm-dd.)
• assign to particular user: use this to assign the incoming Contact or Inquiry record to a specific user. (Use OwnerID: "UserID" and include it in the JSON of the Contact and/or Inquiry.) Click here to locate User ID.

Note: Click here to learn how to locate API field names.

JSON Result

You can use the returned data when building your form to verify the data has been received and processed correctly by Propertybase. It can also be useful if you want to display a custom "Thank You" response to the prospect on the success page.

If there are no errors, "errorMessage" will equal "null". Otherwise, an error message will display.

You can safely ignore the "attributes" structure for contact, inquiry and owner. This is standard information created by the Force.com platform. It is of no use for Propertybase, however cannot be removed from the result.

{
  "errorMessage": null,
  "contact": {
    "attributes": {
      "type": "Contact",
      "url": "/services/data/v25.0/sobjects/Contact/003E000000QUAqnIAH"
    },
    "Phone": "+49 89 123456",
    "Email": "max@example.com",
    "LastName": "Mayer"
  },  
  "request": {
    "attributes": {
      "type": "Request__c",
      "url": "/services/data/v25.0/sobjects/Request__c/a0JE0000006XBWQMA4"
    },
    "pba__Bedrooms_pb_min__c": 2.0
  },
  "owner": {
    "attributes": {
      "type": "User",
      "url": "/services/data/v25.0/sobjects/User/005E0000002OVUwIAO"
    },
    "Email": "tom.smith@brokerage.com",
    "Id": "005E0000002OVUwIAO",
    "FirstName": "Tom",
    "LastName": "Smith"
  }
}

See the "Testing" tab for instructions on how to test your webservice.

Preventing Duplicates

This service aims to identify existing contacts in Propertybase and replace or modify them, rather than creating duplicate records.

Note: Please use this feature with care! We highly recommend overriding data only when you are positive there is an existing contact. It is always better to have duplicates than to overwrite (and lose) existing data.

When an existing Contact is identified, the Contact data in Propertybase can be modified or replaced. However, Inquiry data cannot be overridden. Inquiry data will always be treated as a new Inquiry and attached to the Contact record.

---

Modifying or Replacing

Setting: webserviceWebToProspect_dupeBehavior

Value	Default?	Description
none	no	Disables the check for existing Contacts.
override	no	Overrides all existing values with new values provided within the Contact portion of your JSON string. "Null" values in your JSON string will be ignored.
enrich	yes	Adds new values from the Contact portion of your JSON string if the existing value is null.

Examples:

Existing Contact: LastName = Doe, Phone = +1 12345678

New Data: FirstName = John, Phone = + 1 87654321

Result after enriching: LastName = Doe, FirstName = John, Phone = +1 12345678

Result after overriding: LastName = Doe, FirstName = John, Phone = +1 87654321

---

Identification Strategies

Setting: webserviceWebToProspect_dupeBehavior

Existing Contacts in Propertybase can be identified by:

• Record ID
• External Contact ID fields
• Email address
• Phone number
• Your own custom logic (implemented as a plugin)

The identification methods listed above are prioritized by W2P in the following order:

1. Record ID
2. External ID
3. Custom Plugin
4. Email Address
5. Phone Number

Setting values should be a combination of externalid, email, phone and plugin, separated by semicolon. (ID does not need to be specified.)

For example: webserviceWebToProspect_dupeStrategies = "externalid;phone;plugin"

The Contact Record ID in Propertybase should be specified in your JSON:

{
  "prospect": {
    "contact" : {
      "FirstName": "Max",
      "LastName" : "Mayer",
      "ID" : "0032800000dV8Ja"
    },
 
  . 
  .
  .
  } 
}

---

Identifying Using External ID

To identify Contacts using an external ID, please consider the following.

• Include the setting from above with "externalid" (among others): webserviceWebToProspect_dupeStrategies = "externalid;phone;plugin"
• Include the setting "webserviceWebToProspect_externalIdField" and add the API name of the external ID field you want to query.
• In your JSON make sure to include a name value pair. This should include the API field name of your external ID and the corresponding API name for external ID in Propertybase. See the example below.

webserviceWebToProspect_dupeStrategies = "externalid"

webserviceWebToProspect_externalIdField = "pba__SystemExternalId__c"

{
  "prospect": {
    "contact" : {
      "FirstName": "Max",
      "LastName" : "Mayer",
    "pba__SystemExternalId__c" : "927902842492834"     
    },
 
    .
    .
    .
  } 
}

---

Identifying Using Email Address

To identify Contacts using email address, please consider the following.

• W2P will always look at all email addresses in Propertybase. If a Contact has more than one email field, W2P will compare against all available email fields. If more than one duplicate is found, only one record will be updated.
• It's important that your Contacts in Propertybase do not share email addresses, otherwise this feature will not work.
• Include the setting from above with "email" (among others): webserviceWebToProspect_dupeStrategies = "externalid;email;plugin"
• In your JSON, include at least one email field. See the example below.

webserviceWebToProspect_dupeStrategies = "email"

{
  "prospect": {
    "contact" : {
      "FirstName": "Bobby",
      "LastName" : "Buyer",
      "Email" : "max@example.com"      
    },
 
  .
  .
  .
  } 
}

---

Identifying Using Phone

To identify Contacts using phone number, please consider the following.

• W2P will always look at all phone numbers in Propertybase. If a Contact has more than one phone number, W2P will compare against all available phone numbers. If more than one duplicate is found, only one record will be updated.
• It's important that your Contacts in Propertybase do not share phone numbers, otherwise this feature will not work.
• Include the setting from above with "phone" (among others): webserviceWebToProspect_dupeStrategies = "externalid;phone;plugin"
• In your JSON, include at least one phone field. See the example below.

webserviceWebToProspect_dupeStrategies = "email;phone"

{
  "prospect": {
    "contact" : {
      "FirstName": "Bobby",
      "LastName" : "Buyer",
      "Email" : "max@example.com" 
      "Phone" : "123-456-7891"     
    },
 
  .
  .
  .
  } 
}

---

Identifying Using a Custom Plugin

Using a custom plugin allows you to use your own logic to identify existing Contacts. To add a plugin, simply create a new APEX class and implement the interface pba.WebserviceProspectRest.DuplicateFinder2. Your class must implement a single method for receiving Contact data from your Inquiry. It must also return the ID of a Contact that will be identified as a duplicate or "null" if no duplicate is found.

To identify Contacts using a custom plugin, please consider the following.

• Create a class that implements the interface pba.WebserviceProspectRest.DuplicateFinder2
• Add the name of your class as the value to Setting = webserviceWebToProspect_pluginDuplicateFinder
• Set webserviceWebToProspect_dupeStrategies to include "plugin". See example below.

webserviceWebToProspect_dupeStrategies = "email;plugin"

webserviceWebToProspect_pluginDuplicateFinder = "MyCustomDuplicateFinder"

Example #1

global class MyCustomDuplicateFinder implements pba.WebserviceProspectRest.DuplicateFinder2 {
      
  global Id findDuplicate(Contact c) {
        
    //simple dupe finder based on lastname, firstname
    List<Contact> dupes = [select id from Contact where LastName = :c.LastName and FirstName = :c.FirstName order by created date desc limit 1]; 
    if (dupes.isEmpty()) return null;
    else return dupes[0].Id;
  }
      
}

Example #2

global with sharing class SharingDuplicateFinder implements
pba.WebserviceProspectRest.DuplicateFinder2 {

// dupe finder based on email that uses sharing rules
global Id findDuplicate(Contact c, pba__Request__c r) {
if (c.Email == null || c.Email == '')
return null;

List<Contact> dupes = [select id from Contact where Email = :c.Email order by createddate desc limit 1]; 

System.debug('Duplicates found: ' + dupes);

if (dupes.isEmpty()) return null;
else return dupes[0].Id;
}
}

FAQs

Do security settings apply to de-duplication behavior?

Yes. Organization Wide Defaults, with respect to record sharing, are taken into consideration from the W2P API. This means that if Contacts and Companies are set to "private" the webservice will not be able to identify potential duplicate records and will result in duplicates being created.

In this instance a sharing rule will need to be implemented which enables the webservice user to have access to all records and to check for duplicates are in the system. The easiest way to do this, is to create a Public Group and add the webservice user to it. The public group will allow you to create a sharing rule and include the webservice user.

The sharing rule needs to state "Contact: Owned by members of - "All Internal Users" - Share with the Group - Webservices".

---

Are there service and API limits?

Yes. Any call to this webservice counts towards your daily API usage limit. This limit usually is 1000 calls per full user license with a fixed minimum of 5,000 calls and a maximum of 1,000,000 calls per day.

Examples:

• You are running a brokerage with 15 users: your API limit is 15,000 calls per day
• You are running a small agency with only 2 users: your API limit is 5,000 calls per day
• You are running a multi-national franchise and have 2,000 users: your API limit is 1,000,000 calls per day

In the rare case you exceed these limits, the limits can be enhanced. Please contact your account executive for a quote.

Note: Keep in mind that API calls are also used for other activities. For example: data imports through the APEX data loader. Please make sure your other activities don't consume your API calls, although under normal conditions this should not happen. If you are unsure about your API call usage, please reach out to our support team before importing your data.

---

Why are my fields not populating?

Make sure that the Object Field Permissions have been granted to the webservice user. See the "Anonymous Call" tab on this page for instructions on granting Object Field Permissions.

---

How do I find my endpoint URLs and WebToProspect Token?

• Endpoint URLs can be found in Setup > Sites > Custom URLs. 
• The WebtoProspect token value can be found via the Settings Tab, under the setting "webserviceWebToProspect_token". If the token setting has not been created, your Propertybase Administrator will need to create it. See "3. Add Security Token" under the "Anonymous Call" tab on this page for instructions on creating that setting.

---

Is TLS 1.0 supported?

No. Salesforce has updated security settings and no longer supports TLS 1.0. Please update the SSL version on your webserver to TLS 1.1 or higher.

---

I'm receiving a "field not available" error.

Check you have the exact API Field Name from the Contact or Inquiry object. Click here for more information.

---

Can I assign the new record to a user?

Yes. Simply specify the OwnerID as a field in the Contact or Inquiry JSON.

---

Contact record data is not updating.

First, check if the Contact already exists in the system. If so, de-dupe management is probably set to "Enrich" and the field in question already has data in it. See "Modifying or Replacing" under the "Preventing Duplicates" tab on this page for more information.

---

What is Inquiry data?

If a Contact makes multiple Inquiries, that data should be written to an Inquiries record that will enable you to track multiple Inquiries against a single Contact.

---

I'm receiving a "cannot populate mailing address" error.

Double check you have the correct API Field Name for mailing address. Click here for more information.

---

Does the dupe strategy setting exclude matches?

In this setting webserviceWebToProspect_dupeStrategieswhere the API does not match the first option but does match the second option, the match is still found and the setting does not exclude the match. For instance if an existing contact has a different email but the same mobile, a match is still found based on phone if the setting value is"email;phone" for example. 

information.

---

Why is my dupe strategy  setting not working correctly?

This setting is case sensitive, so check that you entered it correctly for it to work as expected. For example if you have added this setting webserviceWebToProspect_dupeStrategieswith this value value is"email;Phone" , the value should be changed to value to "email;phone" where the field Phone is in a lowercase. Then your setting will correctly find duplicates based on the email AND the Phone field.

 

Wordpress

Currently, there is no Wordpress plugin for the Propertybase WebToProspect API, however a number of clients have added the sample PHP from our public code repository using an Iframe.

From our research, most Wordpress plugins only send form data as an email and do not have the ability to communicate directly with a database. If you are aware of a plugin that can do this, please let our support team know!

The benefit of using a PHP file instead of a Wordpress plugin is that the data is written directly to a Propertybase record. This removes the human element of "translating" email leads into Propertybase. Additionally, you also have control over which data is populated to which field, directly from the from.

Please click here to learn more about setting up WebToProspect.

Testing WebToProspect

Propertybase has created a demo website that can be used for testing your WebToProspect configuration. On this site, click the "Connect" button at the top of the page and enter your specific credentials. Once connected, you will see your Listings on the site and be able to make new inquiries on those Listings.

Note: To remove your endpoint and tokens, click the "Connect" button again, then click the link at the bottom of the window.