- Products
- Solutions
- Developers
- Support
- About
Zoho CRM is a powerful CRM platform that is often a favorite of small and large businesses around the world. For good reason too! Zoho CRM offers a useful, easily extensible tool that allows businesses to keep track of their customer base. Zoho CRM and DOTS validation services are a perfect pairing; Service Objects’ APIs are easy to integrate and Zoho CRM allows users to create custom extensions to use third-party APIs.
This guide will walk you through setting up a custom extension for DOTS Address Validate – US 3 (AV3), and can serve as a reference for integrating any of our services into Zoho CRM extensions.
There are a lot of steps, but rest assured, they are simple and fast. We have broken the process down into its smallest parts.
To get started you will need to request a trial or live production license key from us.
If you are interested in Address Validation – US, you can request a free API trial key here and it will be emailed to you immediately.
(Be sure to check your email account’s junk folder just in case it landed there.)
Log in to your Zoho CRM Developer account and select the “Start Building” button under the Sigma Extension Platform.
In the Sigma extension screen select the blue “New Extension” button in the top right corner.
On form that pops up, give your extension a proper Name, Unique Namespace and Description that will let your users know what the extension will do. We’re selecting Zoho CRM for the service that this extension will apply to. See below for our example.
Now that we’ve created the extension, we’ll need to create some fields that will allow us to store some of the information returned in DOTS Address Validation 3. To do this, select “New Custom Field” with Module list drop down set to Contacts.
For this example, we will only add fields for DPV, DPVDesc, DPVNotesDesc and the IsResidential field that are returned from the DOTS AV3 service. To see what fields would be most appropriate for your application, please visit our developer guide for the service.
For each field, we’ll need to specify a Field Type and Length along with the name of each field. The DPV and IsResidential fields in the AV3 service are short, so these can be set to lower values. The DPVDesc and DPVNotesDesc return longer text descriptions of the different codes that can be returned by the service, so these should be set to the max of 255. All the fields returned in the DOTS AV3 service will be in a string format, so the Field Type can be Text for all of these.
Next, we’ll need to create a workflow that will allow us to call a function that will call the DOTS AV3 service. To do this, select Automate in the Workflow pane on the left hand side.
On the page that pops up, select “Create Rule” under the Rules section.
In the next few pages, we’ll add some custom rules that will tell the extension when to trigger and what exactly to do when it meets the appropriate criteria.
First, name your new rule and then select when you want your new rule to trigger. In this example, we’ll trigger it whenever a new contact is created in our CRM.
Now we’ll implement some criteria that will determine when our rule is called. In this case, we only want to call the DOTS AV3 service when the appropriate address information is present. The minimum amount of information necessary to validate an address is as follows:
Address AND Zip Code
OR
Address AND City AND State
These cases are reflected in the criteria we’ve implemented below. In short, we won’t call DOTS AV3 unless there is an address and zip code or there is an address, city and state information present. Note: The Criteria Pattern will likely need to be edited to produce the appropriate logic. Feel free to add in any other logic that makes sense for your application!
Step 8
Now we’ll set up our new workflow to call a Deluge script that will do the actual call to our DOTS AV3 web service. To do this, select the “+” on the Call Functions section as shown below.
Pressing the “+” button above will bring up Deluge script editor. Deluge is a scripting language that is native to Zoho CRM.
This is where we’ll add the actual Deluge script code to call the webservice. This example has a few different things going on, so we’ll examine it piece-wise to get a better picture of the different things the code is doing. We’ll include a .txt file that will have the code in its entirety.
To start, this function passes in a contact object that we’ll use to get the mailing address to be validated. We’ll also use the code shown below to properly encode the values for HTTP transport. This is also where you will put your license key.
Next, we’ll build out the primary and backup URLs that will be used to get our validated address data. These two URLs are calling our trial endpoints. If you are using a production key, the primary URL should begin with sws.serviceobjects.com and the backup URL should begin with swsbackup.serviceobjects.com. In the code below we have an empty string called AddressTwo that we are using; if you have an Address2 line or a BusinessName for an address, feel free to add those into the request below.
In the next bit of code, we’ll call the primary endpoint and then check the response. If the response is null or if there was a Fatal error returned by the service, we’ll call the backup URL. This Failover configuration will help ensure maximum uptime and availability in the service and ensure that your data gets validated no matter what.
Now that we have some validated address data, we’ll push it back to the CRM and update the existing address fields where we retrieved the data, and we’ll update the custom fields that we created. Note in the code below that we access the AV3 JSON response with the .getJSON() method and then access the first address returned in the AV3 response with the .get(0) method. GetBestMatches can return multiple addresses so for this case we are just selecting the first address. Appropriate logic should be implemented in the event that there are multiple ambiguous addresses returned.
To update the CRM, we’ll build an object to the push to the CRM with the zoho.crm.UpdateRecord method. To do this we essentially create a JSON object with the name of the fields we are updating along with the updated and validated data we want to push back. The info resp; allows us to debug and ensure everything processed as expected.
Your screen should look like the image below. Select Save and Associate to save the function to your extension.
We’ll now test the extension by adding a new contact and ensuring that the workflow rule gets triggered. To start this off select “Test your Extension” in the upper right hand corner.
Click the Contacts heading and then click the “+” symbol to add a new contact to the test CRM.
Enter all the information necessary. In this case that would be name and address. We’ll enter the address info as show below. Note that this address has some mistakes that the service will correct.
Save the contact data and then refresh the record set in your browser. If all went as planned, you should have some newly validated data in your CRM fields! See below for the data our example returned.
Note that the IsResidential, DPV, DPVDesc and DPVNotesDesc fields were previously empty and now contain results from the service. The Address information fields also contain the USPS standardized address data.
As always, we are here to help. If you have questions or would like to learn more about other CRMs, marketing and sales platforms that we integrate with, please feel free to contact us.
© 2024 Service Objects, Inc. All rights reserved.
