Integration API
  • 21 Jun 2022
  • 26 Minutes to read
  • PDF

Integration API

  • PDF

Purpose

The Cloudingo Integration Web Service API provides Enterprise customers the ability 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 involves 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 also is unrestricted by Salesforce governance (CPU limits, query result sizes, looping maximums) because we search these indexes on our own cloud servers.

Newly created or modified records in Salesforce result in index updates in the Cloudingo platform. The speed in 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 your account 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 both REST and SOAP allows customers to program against our platform in the way that is most comfortable 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. 

Note About License Requirements
Access to the Cloudingo Integration API is limited to Cloudingo customers with an Enterprise level license. To establish a Cloudingo license, visit http://cloudingo.com/. Once an organization has an Enterprise level Cloudingo license, Data Integration can be setup and configured via the Cloudingo web portal.


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, select the Integrations option from the dashboard menu.

Assuming that no integrations have previously been created, the screen will automatically display options to create either a new Webservice or a new Callback. The options are also available under the Actions menu.

After choosing the option to create a new Webservice, you will be taken to the Webservice integration Create screen.



Connecting System

The first column on the Web Service Integration screen provides the ability to select what type of system will be connecting to Cloudingo. The default selection is Generic Web Service connecting via REST or SOAP, but other integrated systems may be selected. The remainder of this document is specific to the Generic Web Service. If wanting to integrate with one of the other systems mentioned, please review the documentation specific for that system.





Sample JSON API Requests

You can choose any call type that is checking for duplicates (CheckRecordForDuplicates, CheckForDuplicates, or CheckIdsForDuplicates) to see an example of how both input and output should look like. You must populate the required information (on the middle & right hand column settings) prior to generating an example for viewing. You will want to follow the remaining instructions for configuring these details in the remaining document before attempting to generate the samples.



Cloudingo Integration Details

The middle column will provide some initial details for general integration setup.

Integration Name in Cloudingo

This will provide a description which will display on the Integration dashboard to allow you to distinguish easily between multiple integrations.

Enable Integration in Cloudingo

This will either enable or disable the API service integration. If disabled, the API will respond back with an error code.

Cloudingo Integration Key

This is the unique identifier for your integration which should be sent as a part of the headers when calling the Cloudingo integration API. One will be populated by default, but the key can also be regenerated to provide a new key if desired.

Cloudingo Integration Password

This is the password you can enter which will also need to be passed into the headers when calling the Cloudingo Integration API. In combination with the Cloudingo Integration Key, the Password will authenticate any incoming calls to the API. When initially entered, the password will be encrypted. The encrypted value is what should be passed to the API when called. The plain text version of the password is never shown. However, a new password can be entered at any time. Once the password is saved, the encrypted version will not be shown by default, but can be viewed by clicking on the 'Show Password' button. 

Cloudingo API Call Limit

This is a value that can be adjusted downward in case you want to limit the number of calls within any 24 hour period. While the number of calls can be adjusted, they cannot exceed the default maximum established for your Account.

Allowed API Actions

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

Available Actions

ActionInputOutputVersion
CheckRecordForDuplicatesSet of fields and values for the record to evaluate. The duplicate criteria can be setup on the Cloudingo Integration Dashboard.Integration Action Status Code, Provides a list of potential duplicates per object based on the configuration. If a new record is created, it will provide the new record ID.1.0
CheckForDuplicatesSame as CheckRecordForDuplicates, but will take up to 200 records as an array in a single API call.Same as CheckRecordForDuplicates, but will return an array of results corresponding to the records provided.1.0
CheckIdsForDuplicatesUp to 200 Salesforce IDs passed either via an array or as a query parameter in a single API call.Same as CheckForDuplicates1.0
DetermineMasterDuplicate Records as returned from the check for duplicates method.Integration Action Status, Master record along with any fields that would be changed based on merge rules, and all other duplicate record IDs.1.0
MergeDuplicatesDuplicate Records as returned from the check for duplicates method.Integration Action Status, Master record along with any fields that were changed based on merge rules. 1.0
RestoreBackupBackupId as returned by any method performing a merge, passed either through the body or as a query parameter.Integration Action Status.1.0
PingNoneTime 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.1.0
GetFiltersOptional FilterRequest object to determine if Dedupe or Data Maintenance Filters are requested.List of Filters currently available on the Cloudingo Dashboard along with details of the current Match and Group count in addition to the filter status.1.0
GetFilterGroupsFilter info as returned from the get filters method.List of the filter groups for the filter provided.1.0
GetFilterGroupDetailFilter group info as returned from the get filter group  method.The details for the group. If a dedupe filter, the master and child records will be provided. If a data maintenance filter, the record and update values (if appropriate) will be provided.1.0
RecalculateFilterFilter info as returned from the get filters method.Whether or not the recalculate request was submitted successfully. The status for the filter can be evaluated through the get filters method.1.0
SubmitFilterGroupFilter group info as returned from the get filter group method.Submits the filter group for processing based on the type of filter. For a dedupe filter, the group will either be merged or converted. For a data maintenance filter, the group will either be updated or deleted. 1.0
GetAutomationPreviewsNoneIf the Cloudingo account is setup for automation preview, will return any of the automation previews currently available along with details and status.1.0
GetAutomationPreviewDetailsAutomation preview info as provided by the get automation previews method.Will provide details on the automation preview as well as the corresponding csv content for the automation preview report.1.0
StartAutomationPreviewFilter info as provided by the get filters method.Whether or not the start automation preview request was submitted successfully. The status for the automation preview can be evaluated through the get automation previews method.1.0

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



Salesforce Account and Integration Configuration

The last column on the Web Service Integration screen allows you to select which of your connected accounts the new integration will apply and also provide you options in order to customize the API behavior to your needs.

To begin, choose the Salesforce Account that you wish to configure the API Webservice for. You must connect Cloudingo to the desired org beforehand in order to select the Account from this drop list menu. The available list pulls from your connected platform menu (top left of the page next to the Dashboard menu). If you only have one connected org, it will automatically be defaulted.



This section will determine which objects should be evaluated when performing the Check for duplicates actions as well as which objects can be sent to the Determine Master and Merge Duplicates actions. It is here that you will either select a pre-existing filter from your dedupe dashboard or manually configure the fields to match on, the match options, as well as specify any filters that may be relevant. When selected for a particular object and clicking on the * Options icon, the following screen will be displayed.

* Options Icon

When clicking the Options icon next to the 'Check for (Object) duplicates', you will have the available options:


Example of Duplicate Search on Lead Object

 


  1. Choose an existing filter in the Filter drop list. Options will populate from your pre-built filters located on the dedupe dashboard and can be used for the integration. The filter selected, along with the filter's corresponding/assigned automation rule (which is defined in the dedupe dashboard filter configuration, Tab 1), will be used for the integration. You can also customize (by choosing 'Custom' in the Filter drop box) logic if a Dedupe filter does not already exist for the matching criteria, or if the filter's associated rule differs from what you want applied.
  2. If Custom is selected, the automation rule to use for this particular object must be chosen separately. The automation rule is considered when using the Determine Master method to determine which record should be considered the master, (for example, the most recently modified record) and also when using the Merge Duplicates for both determining the master and determining the values for the master record.
  3.  If Custom is selected, you must also choose which fields to use for matching criteria during the Check for Duplicates action.Each field selected will be expected during the Check for Duplicates call and the system will attempt to match existing records based on these fields. When using a custom filter for the API, the following matches are available:
    1. Exact match with the option to ignore case
    2. First Name synonyms
  4. If Custom is selected, you can also choose which records should be evaluated (this is optional). Here you can evaluate any field to determine if a record should not be included when performing the Check for Duplicates action.
    Example of Duplicate Search Record Limit
    When using a custom filter for the API, the following filter criteria is available:
    1. Field is equal to a specific value
    2. Field is not equal to a specific value
    3. Field has a value
    4. Field does not have a value

       

Include Specific Fields in Response

In addition, under each object that can be used for duplicate check, there is another option expanded.

The "Include Specific Fields in response" option applies to the Check for Duplicates action and will allow you to have a specific field returned from the API call, even though it is not provided when the API is called. For example, if there is a system field that exists on every record that you will want returned with any duplicate found (perhaps to update another external system), you can select the field(s) here using the Options icon (in red), and it will be returned with any duplicate record that is found.

The same configuration logic described here applies to all objects, but each object should be configured independently. For example, if you want to check for Leads and Contacts, you would need to enable both and configure the Options settings for both.



Insert, Update, Merge

This is where you will specify whether you want to create, merge, or update records if a match is or is not detected. 

Create record if no duplicate is found

This option will apply specifically to the Check for duplicates action. When using this option, if no duplicate is found when performing the duplicate check, the API will attempt to create the record. In this scenario, if a new record is created, the new record ID will be returned in the NewRecordID field, and if required fields are missing an error will be returned stating that the create failed and a status message will be returned stating which field was missing. When using this option, a new selection "Manage Create Fields" will appear under the "Check for (Object) duplicates" as shown below:

Clicking on the Options icon will open the following screen:


Example of Manage Create Fields during Create on Lead Object

 

From this screen, you can do the following:


  1. Select to exclude a particular field from the create. You may want to use this if you are providing a system ID to the API, but would not want the value to be used when creating a record. In this case, you would check to exclude the field (all fields are included by default).
  2. Default a value on create. If you wish to default a field on any new record to a specific value, the value can be provided on this screen. Type in the value in the 'Default' box (do not check the box to 'Exclude').


If configuring Duplicate Search on Contacts, select the 'On contact create, use company clean to find Account' option if you want the API to use company clean when evaluating Account names instead of Exact match. If an Account is identified as a match, the Contact will be created under the identified Account (rather than creating a new Account).


If configuring Duplicate Search on both Contacts & Leads, choose which object you would like the new record to be inserted as (Lead or Contact). The default is Contact.



Auto Merge

This option will apply specifically to the Check for duplicates action. If enabled, it will automatically disable the "Update record automatically if single duplicate is found" option and vice versa. When using this option, if one or more duplicates is found when performing the duplicate check, the API will execute a merge based on the specified object's rule if the number of duplicates is less than the set threshold. The available threshold values range from 1-10. When using this option, a new selection will appear in order to set the desired threshold in terms of the maximum number of duplicate matches as shown below:

 

If configuring Duplicate Search on both Contacts & Leads, choose which object you would like the incoming record to be merged into (Lead or Contact). The default is Contact.




Update record automatically if single duplicate is found

This option will apply specifically to the Check for duplicates action. If enabled, it will automatically disable the "Use Auto Merge" option and vice versa. When using this option, if only a single duplicate is found when performing the duplicate check, the API will update the single record with specific values configured. You may want to use this functionality if you assume that the calling system will be more accurate in terms of a specific field than the current record. When using this option, a new selection "Manage Update Fields" will appear under the "Check for Object duplicates" as shown below:

Clicking on the Options icon will open the following screen:

Example of Manage Update Fields on Update for Lead Object

 


From this screen, you can do the following:

  1. Select a field that you would like to update if only a single record is found during the duplicate check. By selecting this option, the API will expect the field to be included in the call to the API. All fields are deselected by default, so you must check the 'Include' box for all fields that you wish to be included.
  2. Default a value on any update for a specific field if only one record is found. If a default is provided, that value will be updated on the record found. Type in the value in the 'Default' box and check the box to 'Include'. 





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 connecting system type
  3. The actions that have been selected
  4. The current status of the integration
  5.  The current API call limit for the integration
  6.  The number of calls made for the integration in the past 24 hours.


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

  • CloudingoIntegrationKey: The auto-generated GUID provided by the Cloudingo Integration Dashboard within the Cloudingo web portal.
  • CloudingoIngegrationPassword: 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 Dashboard and the value will be encrypted. The encrypted value should be passed in the header.
  • 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 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.

    • Inputs:
      1. RecordInfo – Name value pairs of fields and their corresponding values for the new record.
      2. JSON Example
    • Outputs: 
      • An Integration status code for the overall operation.
      • The inputs provided for the duplicate check. 
      • A new record ID if one was created.
      • A merge result if an auto-merge was performed.
      • A list of potential duplicates along with any specific custom fields configured to be a part of the response.
      • JSON Example:
    • Method Specific Response Codes (Detailed below)
      • SuccessActionComplete
      • SuccessRecordAdded
      • SuccessRecordUpdated
      • ErrorMergeNotAllowedBasedOnRules
      • ErrorMergeFailed
      • ErrorRecordCreateFailedMissingData
      • ErrorRecordCreateFailedInvalidField
      • ErrorRecordCreateFailedPermissionDenied
      • ErrorRecordCreateFailed
      • ErrorRecordUpdateFailed
      • ErrorRecordUpdateFailedInvalidField
      • ErrorUnableToDetermineMaster


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.

  • Inputs:
    • RecordInfo: An array of name value pairs of fields and their corresponding values for the new record.
    • JSON Example:
  • Outputs:
    • An array of Duplicate results.
    • JSON Example:
  • Method Specific Response Codes (Detailed below)
    • SuccessActionComplete
    • SuccessRecordAdded
    • SuccessRecordUpdated
    • ErrorMergeNotAllowedBasedOnRules
    • ErrorMergeFailed
    • ErrorRecordCreateFailedMissingData
    • ErrorRecordCreateFailedInvalidField
    • ErrorRecordCreateFailedPermissionDenied
    • ErrorRecordCreateFailed
    • ErrorRecordUpdateFailed
    • ErrorRecordUpdateFailedInvalidField
    • ErrorUnableToDetermineMaster

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.

  • Inputs:
    • IDs: An array of Salesforce IDs, which should be matching Salesforce records.
    • JSON Example:
  • Outputs:
    • An array of Duplicate results.
    • JSON Example:
  • Method Specific Response Codes (Detailed below)
    • SuccessActionComplete
    • SuccessRecordUpdated
    • ErrorIdNotMatchingAnyRecord
    • ErrorMergeNotAllowedBasedOnRules
    • ErrorMergeFailed
    • ErrorRecordUpdateFailed
    • ErrorUnableToDetermineMaster

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.

  • Inputs:
    • List of potential duplicates as provided from the duplicate check methods.
    • JSON Example:
  • Outputs:
    • 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.
    • JSON Example:
  • Method Specific Response Codes (Detailed below)
    • ErrorUnableToDetermineMaster

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.

  • Inputs:
    • List of potential duplicates as provided from the duplicate check methods.
    • JSON Example:
  • Outputs:
    • An Integration status code for the overall operation.
    • Backup ID of the merge.
    • Master record's Salesforce ID.
    • Updated master record details.
    • JSON Example:
  • Method Specific Response Codes (Detailed below)
    • ErrorUnableToDetermineMaster
    • ErrorMergeNotAllowedBasedOnRules
    • ErrorMergeFailed

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.

  • Inputs:
    • BackupId as provided by an of the methods performing a merge.
    • JSON Example:
  • Outputs:
    • An Integration status code for the overall operation.
    • Status message indicating how many records were restored/failed.
    • 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.

  • Inputs:
    • None
  • Outputs:
    • 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.

  • Inputs:
    • FilterRequest: Optional object used to filter the type of filter returned.
    • JSON Example:
  • Outputs:
    • An Integration status code for the overall operation.
    • A list of filters based on the type requested along with record count details and the current filter status.
      • Possible Filter Statuses: Running, ResultsAvailable, ResultsNotAvailable, ExecutionError
    • 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.

  • Inputs:
    • FilterInfo Object represented by one of the filters returned from the GetFilters method.
    • JSON Example:
  • Outputs:
    • An Integration status code for the overall operation.
    • List of filter groups with the group name and record counts provided
    • 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.

  • Inputs:
    • Group info as provided by the GetFilterGroups method.
    • JSON Example:
  • Outputs:
    • An Integration status code for the overall oepration.
    • Master Record
    • Duplicate Records (if a dedupe filter) or Update fields as a record (if an appropriate Data Maintenance filter)
    • 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.

  • Inputs:
    • FilterInfo Object represented by one of the filters returned from the GetFilters method.
    • JSON Example:
  • Outputs:
    • An Integration status code for the overall operation.
    • 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.

  • Inputs:
    • Filter group object as provided by the GetFilterGroups method.
    • JSON Example:
  • Outputs:
    • An Integration status code for the overall operation.
    • 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.

  • Inputs:
    • None
  • Outputs
    • An Integration status code for the overall operation.
    • List of automation previews currently available along with the filter for the preview and status for the preview itself.
      • Possible Automation Preview statuses: Running, ResultsAvailable, ResultsNotAvailable, ExecutionError
    • 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.

  • Inputs:
    • Automation preview object as provided by the GetAutomationPreviews method.
    • JSON Example:
  • Outputs:
    • An Integration status code for the overall operation.
    • CSV content for the automation preview report.
    • 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.

  • Inputs:
    • Filter info object as provided from the GetFilters object.
    • JSON Example:
  • Outputs:
    • 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. 
    • 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: 

  • Daily API Call Limit - based on a 24 hour rolling period. The exact value will depend on the level purchased. 
  • 5 minute period – limited to 1000 API calls in any 5 minute period. 
  • 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.

ActionReasonHttp StatusStatusMessage
AnyMissing Integration Key400ErrorIntegratorConfigurationProblemInvalid Request
AnyMissing Integration Password400ErrorIntegratorConfigurationProblemInvalid Request
Any that requires an inputMissing/Invalid input400ErrorInvalidInputUnexpected input; expecting well formed imput
AnyConcurrent API Limit Exceeded401ErrorCloudingoConcurrentApiLimitReachedInterval Request Limit Exceeded
AnyCloudingo Daily API Limit Exceeded401ErrorCloudingoApiLimitReachedCloudingo API Call Limit Exceeded
AnyCloudingo Subscription Expired401ErrorContactCloudingoSupportCloudingo Subscription Expired
AnyUnable to Authenticate Integration Key or Password401ErrorIntegratorConfigurationProblemUnauthorized Request
AnySuccess - The requested action was not needed.200SuccessNoActionNeeded
AnySuccess Action Complete200SuccessActionComplete
CheckRecordForDuplicates, CheckForDuplicatesSuccess - Record inserted200SuccessRecordAdded
CheckRecordForDuplicates, CheckForDuplicatesSuccess - Existing record updated200SuccessRecordUpdated
AnyError during the requested process. Contact Cloudingo for assistance400ErrorContactCloudingoSupportCorresponding error message.
CheckForDuplicatesMore records passed to the requested action than are allowed400ErrorInputLimitReachedMax Inputs (#) Reached
AnyRequested action is not configured as accessible400ErrorActionDisabledAction Not Allowed
AnyCloudingo profiling/indexing data503ErrorIntegratorTemporarilyUnavailableIntegration temporarily unavailable. Cloudingo is currently re-profiling your data.
AnyError during requested method500ErrorCloudingoSystemProblemCorresponding error message.
CheckRecordForDuplicatesMissing Data prevented record from being created200ErrorRecordCreateFailedMissingDataRequired fields causing the issue
CheckRecordForDuplicates, CheckForDuplicatesInvalid field prevented record from being created200ErrorRecordCreateFailedInvalidFieldInvalid fields causing the issue
CheckRecordForDuplicates, CheckForDuplicatesPermission denied for creating or updating record200ErrorRecordCreateFailedPermissionDeniedFailure message
CheckRecordForDuplicates, CheckForDuplicatesRecord create failed for general reason200ErrorRecordCreateFailedFailure message
AnyConfigured filter information could not be found200ErrorProvidedFilterNotFound
DetermineMasterUnable to determine a master for provided duplicates200ErrorUnableToDeermineMaster
CheckRecordForDuplicates, CheckForDuplicatesInvalid field prevented record from being updated200ErrorRecordUpdateFailedInvalidFieldInvalid fields causing the issue
CheckRecordForDuplicates, CheckForDuplicatesRecord update failed for general reason200ErrorRecordUpdateFailedFailure message
MergeDuplicatesMerge not allowed based on automation rules or exceptions200ErrorMergeNotAllowedBasedOnRules
MergeDuplicatesMerge Failed for general reason200ErrorMergeFailedFailure message

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



Was this article helpful?

What's Next