Let the platform do the work

Integration Overview: All CRM Types


This page  describes the steps required to integrate Sugar Market with an external CRM. It is important to read through this page carefully before proceeding with the CRM-specific topics.


Sugar Market Sync Overview

This section describes the sync process between Sugar Market and all CRM types. The sync process refers to the data you move between your CRM and Sugar Market, the actions that initiate the sync, and the frequency at which the sync occurs. See the guide page specific to your CRM type for field mappings and information on how to set up your sync preferences.

What Gets Synced from Your CRM to Sugar Market?

After the initial sync process, the ongoing sync between Sugar Market and your external CRM occurs for core tables (and custom objects, if applicable) based on the sync preferences you define in Sugar Market. Data is automatically pulled from your CRM into Sugar Market based on the records' last modified date (i.e., records are only synced when the last modified date is after the last sync date) and according to the sync schedule

Core Tables

The following are the core tables that are synced in Sugar Market:

MS Dynamics and Salesforce users may also sync custom objects.

Note: Contacts, Leads, and Candidates are all contained in Sugar Market's Contacts table and are differentiated via the CRMType field.

How Data is Synced from Sugar Market to Your CRM

Unlike the data that is synced down (pulled) from your CRM, data is only synced from Sugar Market to your CRM (pushed) when a corresponding action occurs in Sugar Market. This action can be a manual push or an automation trigger, such as a scoring action, nurture step, or form completion. This means if a change is made to a Sugar Market record, the change will not be pushed to your CRM based on that change, it will only be pushed if there is also a qualifying action. The records modified since the last successful sync are identified by a date field that is unique to each CRM type. Please refer to the CRM Mappings page for your CRM type to determine the specific date field that is used to identify updated records.

The following actions will push data to your CRM:

  • A manual push from a lead/contact card.
  • A condition defined in an event listener is met.
  • A condition defined in a scoring profile is met.
  • A lead/contact flows through a "Push to CRM" nurture step.
  • A "Push to CRM" form action is triggered when a form is submitted by a lead/contact or API call.
  • A lead/contact submits an external form when the external form connector has the "Push to CRM" option enabled.
  • A lead/contact unsubscribed and the "allow updating of unsubscribe status" push option is enabled (the exact option label differs slightly across the CRM types).

Sync Conflicts with Automated Workflows

Since the push sync is often performed as a two-step upsert process, it is important to examine any workflows you may have in place that are defined for insert logic, especially in SugarBPM. If any workflows in your integrated CRM are conflicting with Sugar Market's upsert process, we recommend you add a wait time on insert before executing the automation.

How Duplicate Records are Managed

When pulling data from your external CRM, Sugar Market first checks if the CRM's Contact or Lead ID exists in the Sugar Market Contact table.

  • If yes, then the matching ID record in Sugar Market is updated.
  • If no, then Sugar Market checks if the external CRM's email address exists in the Contacts table.
    • If yes, then the matching email record is updated in Sugar Market.
    • If no, then a new record is created in Sugar Market. 

The same logic is performed when pushing data from Sugar Market to your external CRM (a matching ID is checked first and the email address is checked second). 

Note: Some data pushed from Sugar Market can only use an email address as a unique identifier. If you have multiple records in your CRM with the same email address, these types of data will only be synced to the first record in your CRM that matches the email of the record in Sugar Market. However, if you are integrated with SugarCRM this data can be accessed across all records with the same email address via the Buyer's Journey iframe. 

Planning Your Sync Settings

Before setting up the integration with Sugar Market and your external CRM, we recommend you carefully plan with your Marketing Automation team which data you want to bring into Sugar Market. Consider all use cases to help identify any unique configurations you may need, such as syncing down any custom objects, your CRM is heavily customized, or you plan to upgrade or change your CRM in the near future.

Initial Sync Process

Sugar Market's initial sync process performs the following three tasks to replicate your CRM schema and database:

  1. Replicate Table Structure: Sugar Market replicates the remote table structure of the core tables from your CRM. This process creates a matching field, ordered by field name and data type, on the respective table in Sugar Market. Both standard and custom fields are replicated, but neither inherits or includes referenced extension tables or custom tables.
  2. Replicate Users: Sugar Market downloads all users from the external CRM and inserts them into Sugar Market. In this process, the email address is used to determine if a user account exists in Sugar Market. If an account does not exist, then Sugar Market creates a new record. Sugar Market only downloads the mapped fields in the User table. See the page specific to your CRM type for mappings.
  3. Pull Core Tables: All fields from the core tables are downloaded. Once the initial sync is complete, the recurring, bi-directional sync between the two systems is initiated.
    Note: Sugar Market standardizes the Opportunity schema instead of replicating it as it does with Accounts, Contacts, and Leads.

Sync Process Steps and Schedule

The following table describes the sync activities that occur when Sugar Market pushes data to and pulls data from the CRM:

Process Category Description Steps Activity
Core Sync

Approximately every 10 minutes, the recurring sync process queries for and reconciles in Sugar Market any changes made to the core Account, Lead, Contact, and Opportunity tables in the CRM since the last sync (determined by the ModifyDate field). The sync also commits any new Sugar Market activity to the CRM (if configured in sync settings), with the exception of changes to picklist values in the CRM1

  1. Core Tables: The data schema and fields are pulled down from core tables. All fields that are contained in these tables are synced, even if they do not exist in Sugar Market. If the external CRM has a field that does not exist in the Sugar Market tables, then that field is created in Sugar Market. Fields created in Sugar Market are not created in the external CRM. 
  2. User Sync: The User table is reviewed for any users that have been created or modified in the external CRM since the last sync. 
  3. Score Push to CRM: Scores are pushed to the external CRM Lead and Contact table. This is an optional push that can be disabled in sync settings. This option checks Sugar Market tables for sfScore = 1, indicating that the score has changed for any contact, lead, or candidate. If the score has changed, then one or more score fields are updated in the external CRM. Please refer to the push settings on the page specific to your CRM type for information on how scores are pushed.
  4. Pull Down into Sugar Market: The following tables are reviewed for any changes that have occurred:
    - Users
    - Accounts
    - Leads
    - Contacts
    - Opportunity
    - Marketing list
    - Unsubscribes2
  • Sync the data structure
  • Pull Users, Accounts, Leads, Contacts, and Opportunities
  • Pull marketing lists
  • Push unsubscribes
Email Activity Sync A separate process runs every 10 minutes that pushes data on emails sent to the external CRM. All three pushes are optional and configurable in the Sugar Market connector configuration, which you can access by navigating to the user menu > Administration View > CRM Administrator > External Connectors > [CRM Name].
  1. Sent Emails: Once Sugar Market has captured the delivery status of an email recipient, the respective record in CRM is updated per the connector configuration. The options are to create a Sugar Market Email Activity record or a native Activity (history) record. Sent Email records are pushed to the external CRM in batches of 500.
  2. Opened Emails: When an email sent via Sugar Market is recorded as opened, Sugar Market can optionally create a native activity (history) record, or roll the Open up to the custom Sugar Market Campaign entity.
  3. Clicked Emails: When a link within an email sent via Sugar Market is recorded, Sugar Market can optionally create a native activity (history) record, or roll the Click up to the custom Sugar Market Campaign entity.

If you are concerned about the volume of data created in your external CRM environment, you may want to only push activity that dictates engagement, such as opens and clicks.

  • Push emails sent
  • Push emails clicked
  • Push emails opened
Time-Sensitive Data Sync The last sync thread runs the most frequently and performs these time-sensitive functions.
  1. Tasks: If Tasks have been created from Listeners or Nurture Campaigns, they are pushed into the external CRM. This is based on the existence of an external CRM ID in Sugar Market, not on dates. If the ID does not exist and the Contact/Lead has an external CRM ID, then it is inserted into the CRM.
  2. Lead Creation or Update: If Leads have been created or updated manually or through a form completion, they can be pushed into the external CRM. This is based on a flag in Sugar Market's database that is enabled within each form's actions ("Sync with External CRM"). Leads are created manually by using the "Push into CRM" action on a lead/contact card.
  3. Web Activity: If new Web Activity has been received for a Lead or Contact, then this data is pushed into the external CRM.
  • Push web activity (if selected)
  • Push landing pages
  • Push events
  • Push tasks (if selected)
  • Push new leads (if selected)

1 When picklist values for dropdown fields are added, edited, or deleted in the CRM, they are updated in Sugar Market once per day, not at the normal 20-minute sync cycle.

2 The Unsubscribe service pushes updates to leads, contacts, and candidates. If a record unsubscribes in Sugar Market, the update is pushed to the external CRM's out-of-the-box 'unsubscribe' field (the specific field name is unique to each CRM). If that user is re-subscribed in the external CRM, then the value in Sugar Market is overwritten; however, that record also needs to be removed from the Guarded Watch.

Integration Steps

The following steps are required to set up the sync between Sugar Market and your CRM: 

  1. Installation: See the integration guide page specific to your CRM type for installation instructions.
  2. Create a syncing user: This user needs to have read/write access to everything you want to sync. Once created, the credentials need to be entered into the Sugar Market Connector page.
  3. Create an Iframe role: If you plan to configure the Buyer Journey Iframe in your CRM you will need to create a role that can be assigned to users granting them the needed permissions to access the Iframe.
  4. Allow the Sugar Market IPs.
  5. Identify pull options in Sugar Market connector: Discuss with your team which of the core tables are to be synced, and the approximate number of records to be synced for each. This information is needed when setting up the connector in Sugar Market. See the integration guide page specific to your CRM type for setting pull options.
  6. Request the initial sync: Contact your Sugar Market Implementation Consultant to activate the sync between the two platforms and verify the number of records that have synced down.
  7. Identify Push options in the Sugar Market connector: After the initial sync is complete, define the Push options. See the integration guide page specific to your CRM type for setting pull options.

Creating a Syncing User

Sugar Market requires a user to be allocated in your external CRM for all integrations. This user allows Sugar Market to read and write data from the given CRM. Since some CRMs require that all users' passwords expire after a given amount of time, you will need to reset the password for the syncing user in your external CRM and then update the password in Sugar Market.

Note: Please ensure the syncing user is not used for any other function in your external CRM, as this can cause issues with the integration.

To create a syncing user in Sugar Market:

    1. From the user menu, click "Admin".
    2. In the CRM Administrator section, within the External Connectors tab, click your external [CRM Name].
    3. In the CRM Username and CRM Password fields, enter the username and password for the designated syncing user.
      UserNamePassword Cropped
    4. Click the Save Connection button to the right.

Creating an Iframe Role

The iFrame role in Sugar Market will allow all users in the CRM to access the Sugar Market IFrame directly through the CRM, without having to access Market. All users should be added to this role following the sync with the external CRM. This role must exist in Sugar Market.

To create the Iframe role:

  1. From the user menu, click "Admin".
  2. In the Administrator section, within the User Administration tab, click "Roles".
  3. Create a new role in the system called "iFrame." Refresh the page to see the new role appear in the list.
  4. Double-click the role or select the role and click the pencil icon in the toolbar to open the role editor.
  5. Check the Data Access and Navigation Access checkboxes in the top section.
  6. Click the Save Changes button in the top section.
  7. Click the "Navigation Access" tab next to the "Users" tab on the bottom section and move the permissions you would like to grant to users using the Iframe to "Access Provided":   
    • eMarketing
    • Marketing – Add to Nurture 
    • Marketing – Distribution List 
    • Marketing – Email
    • Marketing – Nurture Architecture
  8. Click the "Save Changes" button in the bottom section.
  9. Once the initial sync with the CRM is complete return to the Roles list view.
  10. Select the IFrame role and click the "Add All Users" icon from the toolbar.

Allowing Sugar Market IPs for CRM Integration

If your CRM web services are inaccessible publicly, they are most likely behind a firewall, which means that Sugar Market will not be able to connect to your web service. To enable the sync between your CRM and Sugar Market, please request your IT and/or CRM Admin to allowlist the following IP addresses. If your CRM web services are open to the public, then you do not need to allow any additional IP addresses.

The following are the outgoing IP addresses from Sugar Market servers that will be connecting to your CRM servers:

Region IP Address Range


Note: The ports are defined via the web service URL you provide. For example, if your web service URL is HTTP, it is port 80. If it is HTTPS, then it is port 443.

Accessing the Sugar Market Connector

The settings that determine the data to pull from your CRM into Sugar Market and push from Sugar Market into your CRM are defined in Sugar Market's external connector settings. Since this page is unique to your CRM type, please visit the Integration Guide page for your CRM to find specific settings. 

To access the external connector settings, navigate to the user menu > Admin > CRM Administrator > External Connectors > your external [CRM Name].

Note: Remember to request the initial sync from your Sugar Market Implementation Consultant before defining push settings.

Custom Objects

Custom Objects are custom tables in your CRM that can sync to Sugar Market. Sugar Market currently supports Microsoft Dynamics CRM and Salesforce custom objects. 

Custom Objects can be used in multiple ways throughout Sugar Market:

  • Segmentation of Lists for better targeting.
  • Personalizing emails with custom object content by using merge tags

While every implementation is unique, here are some uses we have heard from our customers:

  • Product Catalog: Showcase dynamic product information to prospective or current customers, and incorporate details like Product ID, Product Name, Description, Price, etc.
  • Purchase History: Increase conversions and drive revenues by targeting customers who have previously purchased certain products to send "You May Also Like…" emails.

For pricing and more information, please contact your Sugar Market account representative or Sugar Market Support.

Using Custom Objects as Merge Tags in Sugar Market

Once your custom object is configured in Sugar Market, you can view your table through a custom report. The example below is a Credit Card custom object with various fields in the table:


You can then use this report as a custom merge field in your emails.


Consolidating Records

There are a few ways to consolidate records in Sugar Market; the most common methods are to use Sync Filters and Auto-Deletion Reports.

Sync Filters with CRM

Note: Sugar Professional customers do not have access to sync filtering.

You can request specific records or sets of records to sync into the Sugar Market database via sync filters during the initial sync to pull down a subset of records. We recommend you utilize the Sugar Market auto-deletion reports instead because the sync filters only sync down records specified in the filter to Sugar Market, but if a record changes later and does not meet that condition anymore, then it will still exist in Sugar Market. This is because the sync filter is only controlling which records are coming from the CRM to Sugar Market and does not re-reference records once they are in Sugar Market. Please contact your Implementation Consultant or Support if you want to use sync filters.

Auto-Deletion Reports

Sugar Market allows the creation of auto-deletion reports that look for records meeting specified conditions and delete those records. The auto-deletion reports are added to the end of the regular pull sync cycle, which is every 10 minutes, and when the sync cycle pulls down the records that have been modified since the last successful sync, any records that meet the specified conditions are deleted from Sugar Market.

Other Methods

The following options are less common methods of record consolidation, but may be required if your configuration does not allow you to utilize sync filters or auto-deletion reports (e.g., frequent database updates causing too many records syncing down may delay the Sugar Market sync or prevent the auto-deletion report from running).

Manual Removal
  • When removing or deleting the record from the CRM, go to the same record in Sugar Market and delete the record.
Mass Manual Removal
  1. Create a custom field in Sugar Market.
  2. Create a custom report that targets a value of "Delete" in the above custom field.
  3. Gather a list of records that are being removed from the sync filter.
  4. Import the list into Sugar Market updating the custom field to a value of "Delete", and wait for the email confirming this has been completed.
  5. Navigate to the user menu > Admin > CRM Administrator > Data > Mass Delete Contacts by Report, and then select the report you created in Step 2.

After the first time through this process, you will only need to complete Steps 3-5.

Listener/Template Removal (Netsuite Customers)
  1. Create a custom field in Netsuite and let it sync down to Sugar Market.
  2. Create a Contact Update Template in Sugar Market that updates the DeletedDate field to any date value (you must select a specific date).
  3. Create a listener in Sugar Market looking for the custom field value of Delete and set the action of the listener to the template from Step 2.
  4. Instead of removing a record from the saved search in Netsuite, update the new custom field to a value of Delete.
  5. (Optional): After the desired record is deleted from Sugar Market you can now remove the record from the saved search in Netsuite.

Note: Records are not removed from Distribution Lists. When sending a campaign using a list with one of these deleted records, the campaign stats show it as a rejected contact.

General CRM FAQs

The following are frequently asked questions related to Sugar Market integration with any type of CRM:

Question Answer
What happens when I change an email address in an external CRM?

If an email address is changed in the external CRM and synced down into Sugar Market, that record's email is updated and the DelStatus is reset to 0 and the DelMessage is updated to 'Reset by Sync'.

What's the difference between Account Name and Company name? In the external CRM, the company has two different names. Lead records have a Company field and Contact records have an Account Name located in the Accounts table. In Sugar Market, each Lead and Contact has an account record.
How does Sugar Market determine which records to sync down every sync cycle? For each of the core tables selected for Sugar Market to sync down, the integration looks for the record modified date and only syncs those records.
I mass updated records in my CRM but I am not seeing the changes reflected in Sugar Market; why?

When performing any action in a CRM, especially if it is backend-facing (like a SQL update) it is important to verify if the modify date is updated for those records. If you mass update records in your CRM through a workflow or backend, it is highly unlikely that it also updated the modify date of those records. Therefore, Sugar Market would not be alerted of the changes and will not sync those records down. We recommend you also update the modify date of those records.

Is it okay to import Lists into Sugar Market prior to integration? Will this cause duplicates? If you import data into Sugar Market and start sending out campaigns before the integration occurs, all activity performed by that record is preserved. During the integration, records are matched and de-duped based on email address. This overwrites the imported Sugar Market records. Therefore, if you update contact information inside Sugar Market before the integration, that data will be overwritten with your CRM data during integration. The only field that is not overwritten from your external CRM to the Sugar Market CRM is 'unsubscribes' (OptOut).
After the integration between Sugar Market and my external CRM, will there be a delay in our CRM environment due to the constant syncing from Sugar Market? In most cases, no. It is important to note that after initial integration, we are only pulling differentials. Also, we are not "scanning" the records that have changed, we are simply doing an SQL call on the last-modified date that is greater than or equal to last sync date. It is a very quick query with low effort.
Our database is very large (1 million+ records). Should we be concerned about how long the initial sync will take? No need for concern in regard to large database syncs. There are several methods we can take to get your data into our systems such as restricting syncing via the syncing user's permissions, filtering records based on field values, uploading your data locally, or going through our initial sync process. Once the initial sync is complete, the incremental syncs should be very quick and occur multiple times within an hour.
We would like to restrict IP access to Sugar. Do you have a single IP address to provide for IP restrictions? No. While you may simply open all IPs from our IP range, we have a few IP addresses that you would need to allow access to for Sugar Market to connect and integrate.
Do I need a sandbox Sugar Market account? In our experience, the majority of clients that choose to implement a sandbox for testing find that they can test everything they need using their production environment. With this method, Sugar Market can remove any contacts, leads, accounts, and opportunities that synced down during testing. We will not remove any forms or campaigns, nor the activity associated with them. This also allows for fluid testing with actual marketing initiatives created during your training.
Does Sugar Market support VPN for the integration? No, Sugar Market does not support the use of VPN for the integration between both systems. Instead, the integration between the CRM and Sugar Market is done through the respected web services that CRM provides.

Next Steps

Proceed to the topic that is specific to your CRM for more information on setting up your integration with Sugar Market.