Web To Prospect REST API (Preferred)

The Web To Prospect Rest API webservice is an easy way to create contacts, requests and favorites from your own website by calling a simple REST webservice.
 
Want to see how it can look? Visit our "BayAreaBrokers" demo site! You can check out your webservice configuration just by clicking "connect" and see listings from your Propertybase and create real requests in your ORG.

If you are developer? Check out our code repository for web developers
 
The service can be called anonymously or with a valid Force.com Session ID after authentication through standard Force.com authentication methods.

Setting up anonymous webservice

An anonymous webservice requires Sites to be activated for your org. Please activate Sites as described here: http://support.propertybase.com/activating-webservices-in-propertybase-v3/
 

After you have setup Sites, please go to "Public Access Settings", scroll down to "Enabled Apex Class Access", click on "Edit" and add the "pba.WebserviceProspectRestclass.

 
Check the public access settings for fields and objects as described here in step 4 - 5: http://support.propertybase.com/activating-webservices-in-propertybase-v3/

In addition to the describes access rights also grant read, create and edit permissions to the Request object and read/write access to all fields on Request you would like to insert into Propertybase.

 
Your End Point
The webservice will immediately be available at https://yoursitename.secure.force.com/services/apexrest/pba/webtoprospect/v1/
 
Make Sure you add a Security Token
 
To prevent any unauthorized access of this webservice, please include a security token in your calls. The token is stored in a setting called 'webserviceWebToProspect_token' and can be found in the Settings tab. If the Setting does not exist, please create a new Setting record and enter a random string as your own token. We recommend adding a token using a hash generator like this.

Calling the service with a session ID

 
If you prefer using normal authentication, you need to get a session ID first before you can call the webservice. This can be done using several methods, including OAUTH or calling the login method of the SOAP API (a pure REST based login will be available in a future update of the Force.com platform).
 
 
Add this session ID to the header of all your REST calls. A sesson ID will be valid for 2h usually. It makes sense to cache this ID locally to avoid having to login for each call but only if your session is expired.
 
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/"

 
  • Replace sessionId with the
    <sessionId> element that you noted in the login response.
  • Replace instance with your
    <serverUrl> element (if you are not sure, just login to your Propertybase org and check the first part in your URL, after the https://, e.g. na13, eu2 or as1).
  • json.txt has to be text file with a valid JSON string as described below
 

JSON structure

{
     "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
         },
         "requestFromListing": "a09E000000BRg1mIAD",
         "favoriteListings": [
           "a09E000000BRg1nIAD",
           "a09E000000BKh2oBAK"
               ],
         "contactFields": [
           "Email",
           "Lastname",
           "Phone"
         ],
         "requestFields": [
           "pba__Bedrooms_pb_min__c",
           "pba__FullBathrooms_pb_min__c"
         ],
         "ownerFields": [
           "Firstname",
           "Lastname",
           "Email"
         ]
      } 
}
JSON Structure Explained
Security Verification
  • token: is your webserviceWebToProspect_token specified in Settings in Propertybase (see the + Menu). Note this is only required if you call it as an anonymous webservice (see above)

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 from the web form supplied by the prospect that you want written to the Contact record.

  • request; is data written to the Request record. This is a name/value map, where the name is the Request API field name in Propertybase and the value is the data from the web form supplied by the prospect that you want written to the Request record.

    Note: If you also specify requestFromListing, the system will first create the request from your listing data and then apply your specific values, thus potentially overriding the values that have been calculated before

Additional Data (Optional)
  • requestFromListing: if you specify the ID of a Listing here, the system tries to create a request based on the data in this Listing record, e.g. price range around the listing price, number of bedrooms, number of bathrooms, etc.

  • favoriteListings: list of Listing IDs. For each given ID, the system will create a Favorite and attach it to the new Request. If you create your request based on a Listing, make sure to include the Listing ID in this list too.

Returned Data
  • contactFields: list of fieldnames which you want to get returned after your prospect data has been successfully written to Propertybase.

  • requestFields: list of fieldnames which you want to get returned after your prospect data  has been successfully written to Propertybase.

  • ownerFields: list of fieldnames of the new owner (User object) of your Request which you want to get returned after your prospect data has been successfully written to Propertybase.

Other Tips
  • date fields:  to pass in a date into the JSON string to populate a date field in Propertybase use format: yyyy-mm-dd
  • assign to particular user: to make a particular user owner of the contact or request record add "OwnerID: "UserID", to the JSON of contact and/or request. UserID from the particular user. Find here how to identify.
 
See here how to identify the API fieldnames: http://support.propertybase.com/api-field-names/
 
 
JSON result:
 
The data that gets returned can be handy when building your form so that you can verify the data that has been received and processed by Propertybase.
 
It can also be useful if you want to display a custom response to the prospect on the success page, such as "Thanks for your enquiry, our sales agent Tom will be giving you a call." (Tom being the user that this enquiry has been allocated to in Propertybase.) 
 
 
 
{
  "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"
  }
}
 
 
errorMessage will not be null if some error happens. In that case, no other values will be returned.
 
In contact, request and owner, please ignore the "attributes" structure. This is some standard information created by the Force.com platform and is of no use in this case but cannot be removed from the result.
 

PHP example implementation

 
Sample Website
Want to see how it can look? Visit our "BayAreaBrokers" demo site! You can check out your webservice configuration just by clicking "connect" and see your Propertybase listings!

Code repository for the web developers 
 

Preventing Duplicates

 
This service supports to identify existing contacts in the database to replace or enrich the existing data rather than creating duplicates.
 
PLEASE USE THIS FEATURE WITH CARE! Propertybase highly recommends not to override/change any data coming through his webservice if you cannot guarantee this is an existing contact. There are situations where you don't want to override your existing data.
 
You can identify existing contacts in Propertybase by
  • record ID (Id field)
  • some other external ID field on contact
  • email adresses
  • phone numbers
  • your own custom logic (implemented as a plugin)
When an existing contact is identified the contact data in Propertybase can be enriched or replaced (overridden). If you specify some Request data, there will always be a new Request which will then be attached to the existing contact. Requests will never be updated by this webservice.
 

Enriching vs. Replacing

Setting: webserviceWebToProspect_dupeBehavior
 
 Value Default?  Description
 none    disables the check for existing contacts
 override    overrides all existing values with the new values you provide in the contact subelement of your JSON string. Null values in your JSON will be ignored.
 enrich  yes  adds new values from the contact subelement of your JSON string if the existing value is null
 
Example:
 
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
 

Available strategies

Existing contacts can be identified based on their ID, external ID fields, email address, phone number or through your own custom logic which can be added as a plugin to Propertybase.
 
If you specify several strategies, the strategies are executed in the following sequence and the first one always wins:
 
  1. ID
  2. external ID
  3. Plugin
  4. Email
  5. Phone

Setting: webserviceWebToProspect_dupeStrategies

Values: semicolon separated combination of externalid, email, phone and plugin. (No need to specify ID)

    Example webserviceWebToProspect_dupeStrategies = "externalid;phone;plugin"

ID

  1. simply provide the record id of a contact in Propertybase in your JSON
 
Example:
 
{
  "prospect": {
    "contact" : {
      "FirstName": "Max",
      "LastName" : "Mayer",
      "ID" : "0032800000dV8Ja"
    },
 
  . 
  .
  .
  } 
}
 

External ID

  1. Setting webserviceWebToProspect_dupeStrategies: include "externalid" in the value (besides other strategies)
  2. Setting webserviceWebToProspect_externalIdField: add the API name of the external ID field you want to query
  3. In your JSON, make sure to include a name value pair with name set to the API field name of your external ID and the value being a valid external ID in Propertybase
 
Example:
 
Setting webserviceWebToProspect_dupeStrategies  = "externalid"
Setting webserviceWebToProspect_externalIdField = "pba__SystemExternalId__c"
 
{
  "prospect": {
    "contact" : {
      "FirstName": "Max",
      "LastName" : "Mayer",
    "pba__SystemExternalId__c" : "927902842492834"     
    },
 
    .
    .
    .
  } 
}

Email

Matches on Email will always compare all email addresses in your new data to all email addresses in Propertybase. If you have more than one email field, all email fields will be compared. If more than one match is found, only one record will be updated.
 
Note: This will only work reliably if you make sure your contacts do not share the same email address!
 
  1. Setting webserviceWebToProspect_dupeStrategies: include "email" in the value (besides other strategies)
  2. In your JSON, include at least one email field
Example:
 
Setting webserviceWebToProspect_dupeStrategies  = "email"
 
{
  "prospect": {
    "contact" : {
      "FirstName": "Max",
      "LastName" : "Mayer",
      "Email" : "max@example.com"      
    },
 
  .
  .
  .
  } 
}

Phone

Matches on phone numbers will always compare all  phone numbers in your new data to all  phone numbers in Propertybase. As usually more than one phone number field is used in Propertybase, this allows to also match contacts if e.g. the mobile number was accidentally entered as home phone.
 
Note: This will only work reliably if you make sure your phone numbers are stored in the same format, no contacts share the same number and in case of international contacts you also have to include the country code.
 
  1. Setting webserviceWebToProspect_dupeStrategies: include "phone" in the value (besides other strategies)
  2. In your JSON, include at least one phone field
Example:
 
Setting webserviceWebToProspect_dupeStrategies  = "email;phone"
 
{
  "prospect": {
    "contact" : {
      "FirstName": "Max",
      "LastName" : "Mayer",
      "Email" : "max@example.com",
      "Phone" : "089-110234567"
      
    },
 
  .
  .
  .
  } 
}
 
 

Plugin

This allows you to add your own custom logic to identify existing contacts based on your own algorithms. To add a plugin, just create a new APEX class and implement the interface pba.WebserviceProspectRest.DuplicateFinder2. Your class had to implement one single method that receives the Contact data from your request and has to return the ID of a contact that gets identified as a duplicate or null if no dupe is found.
 
  1. Create a class that implements  the interface pba.WebserviceProspectRest.DuplicateFinder2
  2. Add the name of your class as the value to Setting webserviceWebToProspect_pluginDuplicateFinder
  3. Set webserviceWebToProspect_dupeStrategies to include or solely to "plugin"
 
Example:
 
Setting webserviceWebToProspect_pluginDuplicateFinder = "MyCustomDuplicateFinder"
 
//FIRST EXAMPLE
    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;
      }
      
    }
--------------------------------------------------------------------------------------------
//SECOND EXAMPLE
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

Security Settings apply to De-Duplication Behavior

Be aware that Organization Wide Defaults with respect to record sharing are taken into consideration from the web to prospect API. This means that if Companies (Accounts) and Contacts are set to Private this will prevent the webservice from identifying potential duplicate records and will result in duplicates being created.

In this instance a sharing rule will need to be set in place to enable the web service user to have access to all records to check and see if duplicates are in the system. 

The easiest way to handle this is to create a Public Group and add the web service user to it. The public group will allow you to create a sharing rule and include the web service user. 

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

 

Service and API Limits

Any call to this service counts against 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.)
 
CAUTION: Please keep in mind that API calls are also used for other activities like e.g. data imports through the APEX data loader. Although under normal conditions this should not happen, please make sure your other activities don't eat up your API calls! If you are not sure about this, please get in touch with our support team before importing your data.
 

Fields not populating 

Check that the Object field permissions have been granted to the Website User. This can be checked via Set up > Build > Develop > Sites > WebServices >Public Access Settings > Object Settings.

 

Finding your Endpoint URLs & Web to Prospect Token

The Endpoint URLs can be found in Setup > Sites > Custom URLs section. The WebtoProspect Token value can be found via the Settings Tab > webserviceWebToProspect_token. If the Token setting has not been created, request the System Administrator to create this Setting where the Name and the Key is webserviceWebToProspect_token and enter the Token into value. The Token value can be created through a Token generator.

 

TLS 1.0 not supported

Salesforce have updated security settings and no longer support TLS 1.0. Please update the SSL version on your webserver for TLS 1.1 or above.

Field Not Available

Check you have the correct Field/API Names on the Contact or Request Object. See the Help file API Names for more information.

Can I assign the record to a user

Yes you can, you simply need to specify the OwnerID as a field in the Contact or Request Data

Data not updating on Contact

Check if the contact already existed in the system as dupe management is probably set to `Enrich` and the field in question probably already had data in it.

What is Request data?

If a contact makes multiple enquiries then data should be written to the Request record that will enable you to track multiple enquiries against a single contact.

Cannot populate Mailing Address

Check the API Names for Mailing Address, as in the API Names Help file.

 
 

Setting up Web to Prospect with WordPress


There is no WordPress plugin for the Propertybase Web-To-Propspect API, however a number of clients have added the sample PHP from our public code repository using an iFrame.
 
Worpress plugins that we have investigated typically only send the form data as an email and have no ability talk directly with databases (If you are aware of one that can do a HTTP Post please let our support team know).
 
The benefit of using the PHP file over a plugin is that the data is written directly to a Propertybase record and removes the human element of transcribing email enquiries into Propertybase. Additionally you can also control what data is populated to which field in Propertybase directly from the form.
 
Please visit the link below to learn more about setting up the Web-To-Prospect service through a Word Press website.
 
 
 
 
Powered by Zendesk