Webservice

Purpose

The Cloudingo Integration Web Service API allows Enterprise customers to use the Cloudingo platform from their own Enterprise systems. The power to find duplicates, merge data into records, and manage data does not have to be done from the Cloudingo website alone. 

System Design

The Cloudingo platform runs in its own cloud, separate from Salesforce. The setup and configuration involve connecting Cloudingo to your Salesforce cloud and creating endpoints in Cloudingo for your Enterprise system to connect to.

Proprietary Indexing

Cloudingo leverages its own indexes for finding duplicates. These proprietary indexes allow for more complex duplicate scenarios than can be supported in Salesforce Apex and SOQL. The Cloudingo system is also unrestricted by Salesforce governance (CPU limits, query result sizes, looping maximums) because indexes on the Cloudingo cloud servers are used to perform searches.

Newly created or modified records in Salesforce result in index updates in the Cloudingo platform. The speed at which these updates occur is dependent on the system load for both the Salesforce and Cloudingo servers, as well as the Cloudingo synchronization mode being used for your account. An understanding of index updates is fundamental to understanding results. Usually, the timing of index updates is not an issue, but when data is flowing into Salesforce from multiple sources simultaneously, duplicate detection will depend on the indexes being up-to-date.

Web Service Technologies

The Cloudingo Web Service API is provided to customers via standard web services technologies. We support both REST and SOAP technologies.

Dual Support for REST/JSON and SOAP/XML

The dual support for REST and SOAP allows customers to program against our platform in the most comfortable way for that customer. The REST endpoints use JSON as the data format, as is the most common convention in modern web programming. The SOAP endpoints use XML as the data format. SOAP provides WSDL definitions of the web service interface which can be used by tools to generate proxy code. These proxies are convenient for interacting with the web service in a way that is natural to the programming language being used by our customers.

Navigation

1. The Cloudingo Integration dashboard can be accessed by logging into https://app.cloudingo.com. Once logged in, the user is presented with the Dedupe dashboard by default. To access the Cloudingo integration dashboard, choose the 'Integrations' → 'Manage' option from the left-hand-side navigation window.
   
   
2. At the top of the page, choose the 'Webservice' tab.
   
   
3. If no integrations have previously been created, the screen will automatically display an option to 'Create New'. The option is also available under the 'Actions' menu.
   
   
   
4. After choosing the option to create a new Webservice, you will be taken to the Webservice integration Create screen.

Step 1: Cloudingo Settings

1. Integration Name: Give the integration a descriptive name.
2. Salesforce Account: Choose the desired Account that the integration will apply.
   1. If only one org is connected to Cloudingo, it will default automatically.
3. Cloudingo Integration Key: This is the unique identifier for the integration. 
   1. A key will be populated by default but a new key can be regenerated if desired.
   2. This key will be sent as part of the headers when calling the Cloudingo Integration API.
4. Cloudingo Integration Password: Enter any password.
   1. Password entries will be automatically encrypted. 
      1. Plain text version of the password is never exposed but can be viewed from the integration configuration using the 'show password' icon.
   2. In conjunction with the Cloudingo Integration Key, the (encrypted) Integration Password will authenticate any incoming API calls. 
5. Enable Integration: Choose this option to enable the integration. 
   1. Deselect to disable the integration.
6. Daily API call limit: Value can be adjusted downward to limit the number of API calls that Cloudingo can use within a 24-hour period. 
   1. API call limit cannot exceed the default maximum established for the Account.
7. Allowed API Actions: Choose which actions should be available in the API. 
   1. By default, all options are enabled.
   2. Example: Limit the API to not merge records via the API by deselecting that option. Cloudingo will return an Action Not Allowed error if the action is called.
   3. Visit the Allowed API Actions section below (or click here to open the list in a separate browser tab) for full definitions of API actions available.
8. Allowed Filter API Actions: Choose which filter actions should be available in the API.
   1. By default, all options are disabled.
   2. Visit the Allowed API Actions section below (or click here to open the list in a separate browser tab) for full definitions of filter API actions available.
9. Allowed Automation Preview API Actions: Choose which automation preview actions should be available in the API.
   1. By default, all options are enabled.
   2. Visit the Allowed API Actions section below (or click here to open the list in a separate browser tab) for full definitions of automation preview API actions available.

Step 2: Duplicate search settings

Determine which objects should be evaluated when performing the check for duplicates as well as which objects can be sent to determine master and merge duplicates. Pre-existing Dedupe filters can be used, or new filtering logic can be built.

1. Check for Lead duplicates: Choose this option to scan incoming records against existing Leads in Salesforce to identify a match.
2. Check for Account duplicates: Choose this option to scan incoming records against existing Accounts in Salesforce to identify a match.
3. Check for Contact duplicates: Choose this option to scan incoming records against existing Contacts in Salesforce to identify a match.
4. Create record if no duplicate is found: Choose this option to allow the incoming record into Salesforce if a duplicate is not detected.
   1. On contact create, use company clean to find Account: Choose this option to use the 'Company Clean' matching algorithm instead of 'Exact' to search for existing Accounts during the Contact scan.
      1. If a duplicate Contact is not detected, but a matched Account is detected, the newly created Contact (if choosing to create the record as a Contact) can be created under the matched Account.
   2. When checking both Contact/Lead, insert new record as:
      1. Contact: If duplicate scans across both objects do not find a match, newly inserted records will get created as Contacts instead of Leads.
      2. Lead: If duplicate scans across both objects do not find a match, newly inserted records will get created as Leads.
5. Auto-merge: Choose this option to apply the Check for Duplicates action and merge the duplicates detected. 
   1. Rules assigned in the Object Settings (Step 3) will determine how existing field values are retained or updated/overwritten.
   2. Whenever 'x' or less matches are found: Set a threshold for how many duplicates can be merged if more than one record is detected as a match.
      1. Threshold values range from 1-10.
      2. If the scan detects more than the set threshold count in matched records, the merge will not be performed.
      3. Regular maintenance on dedupe filters should help to keep the duplicate matches detected to a minimum. 
   3. When a duplicate is found on both Contact/Lead, merge the incoming record with:
      1. Contact(s): If the scan detects at least one duplicate Contact and one duplicate Lead in Salesforce, this option will merge the incoming record with the duplicate Contact record instead of the Lead.
      2. Lead(s): If the scan detects at least one duplicate Contact and one duplicate Lead in Salesforce, this option will merge the incoming record with the duplicate Lead record instead of the Contact.
         1. Regular maintenance on convert dedupe filters should help prevent scans from detecting duplicates in both objects.  
         2. When enabled, the 'Update record automatically if single duplicate is found' cannot be chosen. The setting allows for either merge or update.
6. Update record automatically if single duplicate is found: Choose this option to apply the Check for Duplicates action and perform specified updates (overrides) to the existing record values.
   1. Updates will only apply if a single record match is detected. If more than one match is detected, the update will not be performed.
   2. Rules for merging data are not applied. The incoming values will always override the existing record values. 
   3. Fields must be configured indicating which values will be overwritten with the incoming record in the Object Settings (Step 3). 

Step 3: Object Settings

Lead setup

Options only appear if 'Check for Lead Duplicates' is enabled in Step 2.

1. Use the active lead assignment rule: Option only appears if lead assignment rules are configured and enabled in Salesforce.
   1. Choose this option to apply the defaulted lead assignment rule in Salesforce on newly created records. 
2. Filter: Choose an existing filter or create custom filter logic to use to identify duplicate matches.
   1. Existing: Choose an existing dedupe filter. The filter name & user dashboard where the filter is located will be displayed for easy selection. The rule already assigned to the pre-configured filter will automatically get applied for merging logic (master and field selections).
   2. Custom: Choose 'Custom' in the drop box to build new filter logic. Matching criteria and options are limited. If needing to use options other than 'Exact', 'Ignore Case', or 'Enable Synonym Matching', pre-build a dedupe filter and choose the filter from the list. 
      1. Automation Rule: Choose a rule from the drop box to tell Cloudingo how to merge the records (master and field selections).
      2. Custom Lead Filter - Matching Fields: Choose the 'Add Field' option to add matching criteria.
         1. Lead Field: Choose a field for matching criteria in the drop box.
         2. Matching Style: Choose a matching style (Exact).
         3. Other Options: Choose desired options (Ignore Case or Enable Synonym Matching if applicable).
         4. Repeat steps until all matching criteria are defined.
      3. Custom Lead Filter - Limit Records (Optional): Choose the 'Add Field' option to add limit criteria.
         1. Lead Field: Choose a field in the drop box.
         2. Condition: Choose a condition (Ex: Equals, Not Equals, Has a Value, Has no Value).
         3. Repeat steps until all limits are defined.
3. Manage Lead Create Fields: Option only appears if the 'Create record if no duplicate is found' option is enabled in Step 2. If checking both Leads & Contacts, the option will only appear if 'When checking both Contact/Lead, insert new record as' 'Lead' is chosen in Step 2.
   1. All incoming record values will get set on the newly created Leads by default. 
   2. Setting up fields in this step is optional. Set up fields to exclude certain fields from the insert or to default a specific value for certain fields to get applied to all records instead of taking the incoming record value. 
      1. Choose 'Add Field'.
      2. Choose a field in the drop box.
      3. Choose 'Exclude' to exclude the field's value from getting set on the newly created Leads.
      4. Or populate a value in the 'Default (optional)' box to apply a specific value for all Lead records created instead of taking the incoming record's value. 
      5. Repeat steps for any additional fields that need to be excluded or defaulted.
4. Manage Lead Update Fields: Option only appears if the 'Update record automatically if single duplicate is found' option is enabled in Step 2.
   1. Choose 'Add Field'.
   2. Choose a field in the drop box.
   3. Fields configured will override the existing record's value with the incoming record's value. 
   4. Populate a value in the 'Default (optional)' box to apply a specific value to all Lead records instead of taking the incoming record's value. 
   5. Repeat steps until all fields for override are configured.
5. Include Specific Fields in Response (optional): Choose this option to apply the Check for Duplicates action and have a specific field returned from the API call. For example, a system field might exist on every record and the values needs to be returned with any duplicate found (perhaps to update another external system). 
   1. Enable the setting by toggling the option on.
   2. Choose a field in the drop box.
   3. Repeat steps for any additional fields that need to be returned from the API call.

Account setup

Options only appear if 'Check for Account Duplicates' is enabled in Step 2.

1. Filter: Choose an existing filter or create custom filter logic to use to identify duplicate matches.
   1. Existing: Choose an existing dedupe filter. The filter name & user dashboard where the filter is located will be displayed for easy selection. The rule already assigned to the pre-configured filter will automatically get applied for merging logic (master and field selections).
   2. Custom: Choose 'Custom' in the drop box to build new filter logic. Matching criteria and options are limited. If needing to use options other than 'Exact', 'Ignore Case', or 'Enable Synonym Matching, pre-build a dedupe filter and choose the filter from the list. 
      1. Automation Rule: Choose a rule from the drop box to tell Cloudingo how to merge the records (master and field selections).
      2. Custom Lead Filter - Matching Fields: Choose the 'Add Field' option to add matching criteria.
         1. Account Field: Choose a field for matching criteria in the drop box.
         2. Matching Style: Choose a matching style (Exact).
         3. Other Options: Choose desired options (Ignore Case or Enable Synonym Matching if applicable).
         4. Repeat steps until all matching criteria are defined.
      3. Custom Account Filter - Limit Records (Optional): Choose the 'Add Field' option to add limit criteria.
         1. Account Field: Choose a field in the drop box.
         2. Condition: Choose a condition (Ex: Equals, Not Equals, Has a Value, Has no Value).
         3. Repeat steps until all limits are defined.
2. Manage Account Create Fields: Option only appears if the 'Create record if no duplicate is found' option is enabled in Step 2. 
   1. All incoming record values will get set on the newly created Accounts by default. 
   2. Setting up fields in this step is optional. Set up fields to exclude certain fields from the insert or to default a specific value for certain fields to get applied to all records instead of taking the incoming record value. 
      1. Choose 'Add Field'.
      2. Choose a field in the drop box.
      3. Choose 'Exclude' to exclude the field's value from getting set on the newly created Accounts.
      4. Or populate a value in the 'Default (optional)' box to apply a specific value for all Account records created instead of taking the incoming record's value. 
      5. Repeat steps for any additional fields that need to be excluded or defaulted.
3. Manage Account Update Fields: Option only appears if the 'Update record automatically if single duplicate is found' option is enabled in Step 2.
   1. Choose 'Add Field'.
   2. Choose a field in the drop box.
   3. Fields configured will override the existing record's value with the incoming record's value. 
   4. Populate a value in the 'Default (optional)' box to apply a specific value to all Account records instead of taking the incoming record's value. 
   5. Repeat steps until all fields for override are configured.
4. Include Specific Fields in Response (optional): Choose this option to apply the Check for Duplicates action and have a specific field returned from the API call. For example, a system field might exist on every record and the values needs to be returned with any duplicate found (perhaps to update another external system). 
   1. Enable the setting by toggling the option on.
   2. Choose a field in the drop box.
   3. Repeat steps for any additional fields that need to be returned from the API call.
      

Contact setup

Options only appear if 'Check for Contact Duplicates' is enabled in Step 2.

1. Filter: Choose an existing filter or create custom filter logic to use to identify duplicate matches.
   1. Existing: Choose an existing dedupe filter. The filter name & user dashboard where the filter is located will be displayed for easy selection. The rule already assigned to the pre-configured filter will automatically get applied for merging logic (master and field selections).
   2. Custom: Choose 'Custom' in the drop box to build new filter logic. Matching criteria and options are limited. If needing to use options other than 'Exact', 'Ignore Case', or 'Enable Synonym Matching', pre-build a dedupe filter and choose the filter from the list. 
      1. Automation Rule: Choose a rule from the drop box to tell Cloudingo how to merge the records (master and field selections).
      2. Custom Contact Filter - Matching Fields: Choose the 'Add Field' option to add matching criteria.
         1. Contact Field: Choose a field for matching criteria in the drop box.
         2. Matching Style: Choose a matching style (Exact).
         3. Other Options: Choose desired options (Ignore Case or Enable Synonym Matching if applicable).
         4. Repeat steps until all matching criteria are defined.
      3. Custom Contact Filter - Limit Records (Optional): Choose the 'Add Field' option to add limit criteria.
         1. Choose 'Add Field'.
         2. Field: Choose a field in the drop box.
         3. Condition: Choose a condition (Ex: Equals, Not Equals, Has a Value, Has no Value).
         4. Repeat steps until all limits are defined.
2. Manage Contact Create Fields: Option only appears if the 'Create record if no duplicate is found' option is enabled in Step 2. If checking both Leads & Contacts, the option will only appear if 'When checking both Contact/Lead, insert new record as' 'Contact' is chosen in Step 2.
   1. All incoming record values will get set on the newly created Contacts by default. 
   2. Setting up fields in this step is optional. Set up fields to exclude certain fields from the insert or to default a specific value for certain fields to get applied to all records instead of taking the incoming record value. 
      1. Choose 'Add Field'.
      2. Choose a field in the drop box.
      3. Choose 'Exclude' to exclude the field's value from getting set on the newly created Contacts.
      4. Or populate a value in the 'Default (optional)' box to apply a specific value for all Contact records created instead of taking the incoming record's value. 
      5. Repeat steps for any additional fields that need to be excluded or defaulted.
3. Manage Contact Update Fields: Option only appears if the 'Update record automatically if single duplicate is found' option is enabled in Step 2.
   1. Choose 'Add Field'.
   2. Choose a field in the drop box.
   3. Fields configured will override the existing record's value with the incoming record's value. 
   4. Populate a value in the 'Default (optional)' box to apply a specific value to all Contact records instead of taking the incoming record's value. 
   5. Repeat steps until all fields for override are configured.
4. Include Specific Fields in Response (optional): Choose this option to apply the Check for Duplicates action and have a specific field returned from the API call. For example, a system field might exist on every record and the values needs to be returned with any duplicate found (perhaps to update another external system). 
   1. Enable the setting by toggling the option on.
   2. Choose a field in the drop box.
   3. Repeat steps for any additional fields that need to be returned from the API call.

JSON Sample

At the bottom of Step 3, an option to 'Show Sample JSON Requests' is available which will display examples of how input and output should look like.

Choose a Request/Method Type. Options include:

1. CheckRecordForDuplicates
2. CheckForDuplicates
3. CheckIdsForDuplicates

Webservice Integration Activity Report

1. To see the details of the calls that have been made, navigate to the Reports Dashboard by choosing the 'Reports' → 'Reports' option from the left-hand-side navigation window.
   
2. Search for the Webservice Integration Activity report on the reports dashboard. 
   1. If the report is not enabled, you can enable it under 'Actions' → 'View Reports' (top right in the reports dashboard).
      
   2.  Check the box next to the report name and 'Save'.
      
      
3. The report output will provide the ServiceName, Method, Status, StatusMessage, Date.
   
   

Allowed API Actions

In this section, choose which actions should be available in the API. By default, all options are enabled, but the options can be restricted if desired. For example, to limit the API so that merge records cannot be performed via the API, deselect that option and Cloudingo API will return an Action Not Allowed error if the action is called. 

Available Actions

See detailed Inputs, Outputs, and Method Specific Response Codes for each Action described further in this article below.

Web Service Integration Dashboard Display

After a Web Service Integration has been created, it will display on the Integration dashboard similarly to the following:

This will provide a brief summary of the configured integration including the following:

1.  The name of the integration.
2. The number of calls made for the integration in the past 24 hours.
3. The actions that have been selected.

Endpoints

The Cloudingo Integration API is currently available via SOAP (XML based) or REST (JSON based) service endpoints. The functionality and methods available for both are identical. However, the end point, as well as the manner for initiating the call and handling return values, will vary based on the type of service. All endpoints are handled over SSL.

REST Endpoints

Production Environment: https://api.cloudingo.com/rest/{ActionName}

SOAP Endpoints

Production Environment: https://api.cloudingo.com/soap/

Production Environment WSDL: https://api.cloudingo.com/wsdl

Security

As mentioned, only SSL (https) communication is available for the Cloudingo Integration API. Security for the Cloudingo Integration API is handled via a combination of the Cloudingo Integration Key and the Cloudingo Integration Password which should be added to the headers of any REST or SOAP service call. The following headers should be applied as HTTP headers.

Service Call Headers

1. CloudingoIntegrationKey: The auto-generated GUID provided by the Cloudingo Integration Wizard within the Cloudingo web portal.
2. CloudingoIntegrationPassword: The supplied password to be used to authenticate the caller in combination with the integration key. The password can be entered on the Cloudingo Integration Wizard and the value will be encrypted. The encrypted value should be passed in the header.
3. CloudingoApiVersion (optional): The version of the API to call. If you are planning on continuing with the version available during setup, this should be supplied with all calls. If not provided, this will default to the latest version of the API. Therefore, if not provided, a new API version release will result in all calls automatically upgrading to the latest API. If this is not desired, the version can be supplied so that the caller can control when the API version is upgraded.

Available Actions (Detailed Inputs, Outputs, Response Codes)

We previously described the available actions in this article. This section will detail the inputs, outputs, & method-specific response codes for each action.

CheckRecordForDuplicates

Will evaluate the current data in your organization based on the inputs to determine any possible duplicates using the configured duplicate definition. If configured, it will insert a new record if no duplicate is found, and either update an existing record if only one duplicate is found OR perform an auto-merge of the new record with one or more duplicates that are found (maximum number of matches available to be set for this operation is 10). Otherwise, it will return a list of potential duplicates. If a new record is created, the new record ID will be returned. If an auto-merge is performed, the result of the merge will be returned (similarly to the MergeDuplicates method's response). May also be configured to provide custom fields as part of the duplicate response. A maximum of 200 duplicates may be returned for any given record.

1. Inputs:
   1. RecordInfo: Name value pairs of fields and their corresponding values for the new record.
   2. JSON Example:
      
2. Outputs: 
   1. An Integration status code for the overall operation.
   2. The inputs provided for the duplicate check. 
   3. A new record ID if one was created.
   4. A merge result if an auto-merge was performed.
   5. A list of potential duplicates along with any specific custom fields configured to be a part of the response.
   6. JSON Example:
      

CheckForDuplicates

Behavior is identical to the CheckRecordForDuplicates but will take an array of potential records and respond with an array of results corresponding to the records provided. This method is limited to a maximum of 200 records.

1. Inputs:
   1. RecordInfo: An array of name value pairs of fields and their corresponding values for the new record.
   2. JSON Example:
      
2. Outputs:
   1. An array of Duplicate results.
   2. JSON Example:
      

CheckIdsForDuplicates

Behavior is similar to the CheckForDuplicates but will take a list of IDs that should be matching Salesforce IDs of the records for whom the check should be performed and respond with an array of results corresponding to those records. This method is limited to a maximum of 200 IDs, which can be passed either through an array of IDs, or as the "IDs" query string parameter.

1. Inputs:
   1. IDs: An array of Salesforce IDs, which should be matching Salesforce records.
   2. JSON Example:
      
2. Outputs:
   1. An array of Duplicate results.
   2. JSON Example:
      

DetermineMaster

This method will take results from the duplicate check method and will provide a preview of what will occur if the merge is submitted. Will review the potential duplicates and determine the master record as well as evaluate the field values to determine if any values will be changed on the master record as a part of the merge process. This essentially provides a merge preview without performing the actual merge operation. The rules for master selection as well as the determination of field values can be configured within Cloudingo.

1. Inputs:
   1. List of potential duplicates as provided from the duplicate check methods.
   2. JSON Example:
      
2. Outputs:
   1. List of the duplicates eliminated and the record determined to be the master. If the master record was updated based on the data from the duplicates (depending on configuration), the updated fields will be returned.
   2. JSON Example:
      

MergeDuplicates

This method will take results from the duplicate check method and will perform a merge operation for the list of duplicates and respond with the result of the merge. Will review the potential duplicates and determine the master record as well as evaluate the field values to determine if any values will be changed on the master record as a part of the merge process. The rules for master selection as well as the determination of field values can be configured within Cloudingo. By default, the incoming record cannot be selected as the master regardless of the master selection criteria defined in Cloudingo. However, when field level values are evaluated between records, the incoming record is always considered the newest. If additional details are desired to be provided for the evaluation during the merge process, additional field values can be provided in the Details section of the DuplicateItems list for each duplicate.

1. Inputs:
   1. List of potential duplicates as provided from the duplicate check methods.
   2. JSON Example:
      
2. Outputs:
   1. An Integration status code for the overall operation along with the corresponding message.
   2. Backup ID of the merge, if applicable.
   3. Master record's Salesforce ID.
   4. Updated master record details.
   5. JSON Example:
      

MergeRecords

This method will take Salesforce IDs of the records desired to be merged, arranged as follows:

1. MasterRecordId (optional): main record's Salesforce ID into which all the records will be merged
2. ChildIds: array of 1 or more Salesforce IDs of records that are to be merged

The method will then proceed to perform a merge operation on the desired records and respond with the result of the merge. It will evaluate the fields values to determine if any values will be changed on the master record as a part of the merge process. In case no ID is provided as Master, at least 2 IDs shall be passed as Children and the corresponding master selection rule will determine the master record among them. The rules for master selection as well as the determination of field values can be configured within Cloudingo. This method is limited to a maximum of 200 IDs in total (i.e., ChildIds array has a limit of 199 IDs in case a Master is provided, and 200 otherwise), and the method’s inputs can be passed either through a well-formed JSON/XML body, or as query string parameters.

1. Inputs:
   1. MasterRecordId (optional) - Salesforce ID of the desired master record
   2. ChildIds - array of Salesforce IDs of records to be merged
   3. JSON Example:
      
2. Outputs:
   1. An integration status code for the overall operation along with the corresponding message
   2. Backup ID of the merge, if applicable
   3. Master record's Salesforce ID
   4. JSON Example:
      

ResumeTask

Will resume the task based on a Task ID provided, which can be passed either through the body or as the "TaskId" query string parameter.

1. Inputs:
   1. TaskId as provided by any applicable callback
   2. JSON Example:
      
2. Outputs:
   1. An integration status code for the overall operation
   2. Status message, if applicable
   3. JSON Example:
      

RestoreBackup

Will restore back the records that were merged together based on a merge Backup ID provided, which can be passed either through the body or as the "BackupId" query string parameter.

1. Inputs:
   1. BackupId as provided by an of the methods performing a merge.
   2. JSON Example:
      
2. Outputs:
   1. An Integration status code for the overall operation.
   2. Status message indicating how many records were restored/failed.
   3. JSON Example:
      

Ping

General method for not only determining the status of the Cloudingo Integration API, but will also provide guidance of possible upcoming maintenance windows. For this method, a HTTP GET should be performed. All others should use HTTP POST.

1. Inputs:
   1. None
2. Outputs:
   1. Time in total minutes from the current time until the next expected outage. If there is no scheduled maintenance window upcoming, this will return a negative number referring to the last maintenance window in the past.

GetFilters

This method will provide the current details and status of filters that are present on the Cloudingo Dedupe and Data Maintenance dashboards.

1. Inputs:
   1. FilterRequest: Optional object used to filter the type of filter returned.
   2. JSON Example:
      
2. Outputs:
   1. An Integration status code for the overall operation.
   2. A list of filters based on the type requested along with record count details and the current filter status.
      1. Possible Filter Statuses: Running, ResultsAvailable, ResultsNotAvailable, ExecutionError
   3. JSON Example:
      

GetFilterGroups

This method will provide group details for the filter. Details will be provided for a maximum of 500 groups at a time. In order to get additional groups for a particular filter, the GroupSet requested can be adjusted.

1. Inputs:
   1. FilterInfo: Object represented by one of the filters returned from the GetFilters method.
   2. JSON Example:
      
2. Outputs:
   1. An Integration status code for the overall operation.
   2. List of filter groups with the group name and record counts provided
   3. JSON Example:
      

GetFilterGroupDetail

This method will provide details for a particular filter group based on the result returned from the get filter groups method. If a dedupe filter, the master a duplicate records will be provided. If a data maintenance filter, the record and corresponding update values will be provided (if applicable). This provides a preview of the action result without performing the action itself. Therefore, you can review the merge results prior to submitting the merge itself.

1. Inputs:
   1. Group info as provided by the GetFilterGroups method.
   2. JSON Example:
      
2. Outputs:
   1. An Integration status code for the overall oepration.
   2. Master Record
   3. Duplicate Records (if a dedupe filter) or Update fields as a record (if an appropriate Data Maintenance filter)
   4. JSON Example:
      

RecalculateFilter

This method will start the process of recalculating a provided filter in order to provide updated results. While the filter is recalculating, the status can be evaluated from the GetFilters method.

1. Inputs:
   1. FilterInfo: Object represented by one of the filters returned from the GetFilters method.
   2. JSON Example:
      
2. Outputs:
   1. An Integration status code for the overall operation.
   2. JSON Example:
      

SubmitFilterGroup

This method will submit a filter group for processing based on the type of filter for the filter group provided. If a merge filter, then a merge will be initiated. If a convert filter, then a convert will be submitted, etc. Regardless of the type of filter, the input and outputs are the same and will respond with the same format.

1. Inputs:
   1. Filter group object as provided by the GetFilterGroups method.
   2. JSON Example:
      
2. Outputs:
   1. An Integration status code for the overall operation.
   2. JSON Example:
      

GetAutomationPreviews

This method will return a list of all of the current automation previews available for a Cloudingo account. Automation preview is an advanced feature available which will provide a report of master and duplicate details for a filter result which can be reviewed prior to running automation on a filter result. This required specific configuration and is not enabled by default on a Cloudingo account. However, if enabled and configured, this method will return any reports available along with their current status and some details on the results.

1. Inputs:
   1. None
2. Outputs:
   1. An Integration status code for the overall operation.
   2. List of automation previews currently available along with the filter for the preview and status for the preview itself.
      1. Possible Automation Preview statuses: Running, ResultsAvailable, ResultsNotAvailable, ExecutionError
   3. JSON Example:
      

GetAutomationPreviewDetails

This method will return the details for the requested automation preview. This will primarily consist of the CSV content for the automation preview report. The CSV is exported using UTF-8 encoding.

1. Inputs:
   1. Automation preview object as provided by the GetAutomationPreviews method.
   2. JSON Example:
      
2. Outputs:
   1. An Integration status code for the overall operation.
   2. CSV content for the automation preview report.
   3. JSON Example:
      

StartAutomationPreview

This method will initiate the creation of an automation preview report for a particular filter provided. Not all filters are eligible for automation preview even if automation preview is available in a Cloudingo account as they may not all be appropriate as automation preview is configured per object and other filters do not have an automation preview (Data Maintenance, etc). If the filter provided is not eligible a status message will be sent in the response to notify the caller. The overall status of the preview itself can be reviewed using the GetAutomationPreviews method.

1. Inputs:
   1. Filter info object as provided from the GetFilters object.
   2. JSON Example:
      
2. Outputs:
   1. An Integration status code for the overall operation. The status message on a successful response will provide the automation preview report ID that was initiated. 
   2. JSON Example:
      

Action Workflows

The following section provides details on the overall workflows for particular Cloudingo API actions. While separate actions are provided, in some scenarios the actions work together in order to provide overall functionality depending on each client’s usage pattern.

Duplicate Check and Merge Workflow

Merging with Automation Rules

There are a few things to consider when using automation rules to merge in conjunction with the API as follows.

1. The record being passed to the API cannot be the master record when performing a merge. When performing a duplicate check, we do not require a full record in order to perform the duplicate check but a full record would be necessary if the API were expected to insert records which would satisfy all of the Salesforce validation rules. In addition, if the incoming record could be chosen as the master, there is a greater likelihood that incoming records would fail on create and leave duplicate records within the system. As a result, we do not expect complete records passed to the API when performing the duplicate check and merge.

2. While we cannot select the record passed to the Cloudingo Integration API as the master when determining a master record, all field values will be included in the merge process when determining which field level values should be selected for the master record. In this situation, the incoming API record would be considered the newest record. So, if the desired result would be to have values from the incoming record maintained post merge, your rule would be to preserve the newest value.

Duplicate Check and Determine Master Workflow

Filter Processing Workflow

Automation Preview Workflow

Limits and Conditions

There are a number of checks that occur with each API call as well as Cloudingo API limits and Salesforce API limits. As a result, there is an overall process flow involved with performing actions through the Cloudingo Integration API when these checks come into play and a number of potential return messages if limits or conditions are met. The following is a list of the primary call limits: 

1. Daily API Call Limit - based on a 24 hour rolling period. The exact value will depend on the level purchased. 
2. 5 minute period – limited to 1000 API calls in any 5 minute period. 
3. Concurrent API Calls – limited to 100 API calls processing at any given time.

Limits and Conditions Workflow

Return Statuses

The return details will be provided with each return method. Those listed below without a corresponding action apply to any action.

Any method level error response will have the same structure as shown below. Non-method level errors will be listed in the corresponding status and status message as a part of the response object for the specific method.

General Error Response JSON:
For SOAP, exceptions will all be WebFaultExceptions of type CloudingoApiError which will include a Message, ReferenceNumber, and Status.

Customizations

Customizations to the base Cloudingo Integration API are available on a case by case basis. If you have specific requirements or system integrations that are not covered by the existing API, please contact Cloudingo to discuss your needs.

SOAP Examples

The following examples show a SOAP sample call to both the Ping and the CheckForDuplicates methods. These examples use SOAP UI, which can be downloaded from https://www.soapui.org/

Ping

CheckForDuplicates

REST Examples

The following examples show a sample REST call to both the Ping and the CheckForDuplicates methods.  These examples use Postman which is a Chrome add-on, which can be downloaded from https://www.getpostman.com/

Ping

 CheckForDuplicates