Skip to main content
Act-On Software

SugarCRM 8.x and 9.x Integration User Guide


This article describes the setup and use of Act-On's SugarCRM integration with all SugarCRM 8 and 9 versions.

Act-On's integration with SugarCRM allows you to share lead and contact information between your SugarCRM and Act-On databases. The integration allows SugarCRM users to see lead scores based on prospect behavior with Act-On marketing materials (e.g. emails, web forms, landing pages and your company website).

A bidirectional relationship with SugarCRM allows you as the marketing user to push and then pull data between the two systems synchronizing the two databases. When using the SugarCRM integration you may use not only the SugarCRM standard fields for marketing and segmentation but all custom fields associated with leads and contacts as well.

When importing from SugarCRM you can pull your full list of leads or contacts into Act-On. Importing leads or contacts will create a list within Act-On that contains all of the individuals associated with that group. You can then send email campaigns to them, segment and manipulate the data, or add newly qualified leads to the list for creation in your SugarCRM account.

Basics – What You’ll Need to Begin

  • SugarCRM version 8.x or 9.x
  • SugarCRM administrator privileges
  • SugarCRM username
  • SugarCRM password
  • SugarCRM URL
  • SugarCRM Module Installer Zip File: DOWNLOAD NOW
  • SugarCRM Platform Package Zip File: DOWNLOAD NOW

On premise only: You must also whitelist the following IP address: in your corporate IT system. Please work with your internal admin to accomplish this.

  1. From the Start page, click on Settings, and choose Connectors.
  2. Click the SugarCRM logo, or click CRM > SugarCRM.
  3. Click Connect.
  4. Enter your SugarCRM login credentials.
  5. Click Login.

Install the Act-On Package within SugarCRM 


Important: If you already have the package but need to upgrade versions, you must uninstall it before proceeding.

  • Navigate to SugarCRM and go to Admin (upper right hand corner)
  • Scroll down to Developer Tools and click Module Loader
  • Find the old Sugar plugin and click Delete Package

Start by having the following ready during or before SugarCRM installation: 

  • The installation zip file downloaded to your desktop
    • Please note that MACs may unzip the file. In order to load the file within SugarCRM, you may need to re-compress the file prior to uploading.
  • Have SugarCRM and Act-On open within your browser
  • Have your ci instance name available (i.e.
    • If you are unsure of what that is, please look the browser bar for your Act-On instance:

Note: This is just an example.

To install the package:

  1. Log into your Act-On Account
  2. Click on Settings > Apps > API Access > Generate Key
    Please note:
    If you do not see the 'Apps' button, please contact Support to have the 'OAUTH' feature enabled.
  3. Copy the key that is provided
  4. Navigate to the Admin menu in the dropdown at the top left corner of your screen
  5. Navigate to Developer Tools and select the Module Loader
  6. Click on Choose file or Browse to select a file:
  7. Select the .zip file from the download link above and click Install Commit
  8. After successfully installing the file, go back to the Admin panel in SugarCRM and select System > Repair
  9. Click Quick Repair and Rebuild - The bottom of the page will show 'done' once completed
  10. After successful install, return to Admin > System > Connectors
  11. Choose Set Connector Properties
  12. If you are not already on the tab called Act-On Integrator, click on that tab:
  13. In the URL (Global) text box, enter the URL associated with your Act-On Account. The URL will be where the ciXX is replaced with your ci found in your browser address bar when logged into Act-On.
  14. Paste the API key that you copied from your Act-On account into the API Key (Global) field.
  15. Click Test Connector
  16. IF  you plan on connecting more than one Act-On Account to your SugarCRM, please follow these steps below: (otherwise, skip!!)
    • Enter the number of additional  teams in "Number of additional Teams".  In the example below, we are connecting one more Act-On account to a SugarCRM Team.  (For information on how to set up SugarCRM teams, please search within SugarCRM documentation)
    • Enter the Team Name in the text box. The team name MUST MATCH the exact Team Name in Sugar. This is also case sensitive.
    • Enter the Team URL. The URL will be where the ciXX is replaced with your ci found in your browser address bar when logged into Act-On.
    • You will have to go into your additional Act-On Account to get the API Key and enter it into the Team API Key 1. (Within Act-On, Click on Settings > Apps > API Access > Generate Key)
      • You will repeat these input values for as many Act-On accounts that you are connecting to this SugarCRM instance. 
    • Click Test Connector
Note: You may have to click  "Test Connector" twice.

If it fails with the IP address only, copy the IP address given to you and authorize it in your Act-On account. Below is an example of what it will look like. It will say 'Illegal Remote Endpoint with an IP Address'.

  • The IP address that it gives you will need to be copied and pasted into the Act-On Account(s)
  • Copy the IP address and go to Act-On
  • Click on Settings Apps > API Access > Authorize IP


  • Paste the IP address making sure there are no extra spaces and click Submit
  • Go back in SugarCRM and click Test Connector again:

You should see a Test Successful message. If not, please validate that the URL, API Key and IP addresses are correct and test again.

Click Save

  • If you are not already on the Connectors page, navigate back to the Connectors page by going to SugarCRM: Admin > System > Connectors:
  • Click Enable Connectors:
  • Click on the Act-On Integrator tab:
  • Ensure that Contacts, Leads and Targets are under Enabled. If not, move them to Enabled and click Save.

Click Save

Install the Platform package within sugar


Note: As of the Winter 2018 release, Sugar requires that external APIs be registered in the ‘Platform’ field of each Sugar instance in order to integrate. This is a prerequisite for customers to upgrade to Sugar's V11 API Endpoint for retrieving records, which may resolve issues with timeouts related to syncing tagged records. This article describes the process for registering the Act-On platform in Sugar, you can find more information about the platform requirement here.

    • Please note that MACs may unzip the file. In order to load the file within SugarCRM, you may need to re-compress the file prior to uploading.
  • Navigate to the Admin menu in the dropdown at the top left corner of your screen.
  • Navigate to Developer Tools and select the Module Loader.

Screen Shot 2018-11-20 at 2.36.10 PM.png

  • In the Module Loader, click on Choose File or Browse.
  • Select the act-on-custom-platform-1.0 file in the finder and click Upload.Screen Shot 2018-11-20 at 2.36.39 PM.png
  • Locate the Act-On Custom Platform Registration package below the Module upload tool and select Install and Commit.
  • Verify that the Act-On Custom Platform Registration package has been successfully installed in the Module Loader.

Screenshot from 2019-05-15 08-36-15.png - Latest 15/May/19 8:37 AM - Jamie Hartman

  • Navigate back to the Administration page and click on Configure API Platforms in the Developer Tools section and confirm that ‘act-on’ has been added to the API Platforms list.

Screen Shot 2018-11-20 at 2.38.53 PM.png


To enable the Dashlets within SugarCRM:

  1. Log out of SugarCRM and close all browser sessions completely
  2. Log back in
  3. Go to the main Dashboard (the sugar cube in the upper left-hand corner)
  4. Click Leads and access any lead record. (For this version you may have to add it to the specific contact/lead level – i.e., you cannot add it at the global lead/contact level however once added it will add to all leads/contacts)
  5. Once in the individual lead record, click Create in the upper right-hand corner
  6. Click Add a row then click Add a dashlet
  7. Select the Act-On Activity History dashlet from the available list
  8. Choose the appropriate marketing behaviors you would like displayed, then Save
  9. Repeat these steps to Add the Marketing Timeline dashlet
  10. Give this Dashboard a name such as, Act-On Activity
  11. Repeat all of these steps again in a Contact record. Click Contacts and access any contact record.
  12. Go to the dashboard (cube icon in left corner) within SugarCRM to enable Hot Prospects
  13. Click on Edit in the upper right hand corner
  14. Click Add a Row, click Add a Dashlet
  15. Select Act-On Hot Prospects dashlet from the available list.
  16. It will give you the option to customize the options as seen below:
  17. Name your Dashboard and click Save.
  • Max Records – Number of records displayed in the Hot Prospects Dashlet
  • Days of History – Number of days viewed of Act-On Activity History
  • Minimum Score – Minimum value of lead score to have one appear in the Hot Prospects dashlet
  • Include Email Sends – Include the Act-On lead score value for ‘was sent a message’ in the calculation
  • Include Email Opens – Includes the Act-On lead score value for ‘opened a message’

Import/Synchronizing Lists

  1. Log into your Act-On account
  2. From the Start page, click on Contacts > Marketing Lists.
  3. Click Import, and choose from the available lists.
  4. Change the name of the list being imported to Act-On, if desired.
  5. Click Next, and select any fields you wish to import from SugarCRM to Act-On.
    • The imported data can be used to make segments in Act-On, as well as personalize messages. Fields can be added and removed after the initial import. There are a couple special fields that we highly recommend you import:
      • Email – Act-On uses email as the key to track behavior, so this is important to include
      • Act-On Lead Score – This is a new custom field that was created in SugarCRM via the Act-On connector (see Step 1 above). It is meant to be used to contain the Act-On lead score. If you would like to see the Act-On lead score in SugarCRM, then select this field.
      • Assign To – Act-On uses 'Assign To' for lead/contact owner association for hot prospects
  6. Click Finish.
  7. Repeat these steps to import other lists.

Once your marketing lists are imported from SugarCRM, it is important to make sure your SugarCRM and Act-On lists are synchronized.

The initial import is only a one-time event. If you wish to keep the list synchronized with SugarCRM, an automated sync can be enabled.

Follow the steps below to synchronize your SugarCRM lists with Act-On:

  1. Hover over the SugarCRM marketing list you wish to sync, and click the drop-down arrow.
  2. Choose Import/Export > SugarCRM Sync Setup.
  3. Enable the option to push to and/or pull from SugarCRM.
    • Typically, Act-On users will push the Act-On lead score to SugarCRM, and pull all of the other values. To enable this:
      1. Click the Push to SugarCRM checkbox
      2. Click the Update checkbox under Push
      3. Click on the Select Push-Update Fields link
      4. Select Act-On Lead Score
    • After saving:
      1. Click Pull from SugarCRM
      2. You can then choose to click the Add checkbox if you would like new contacts to be added into Act-On (most users select this). Or, Remove can be checked if you would like to remove contacts from Act-On that were removed in SugarCRM.
      3. Check the Update checkbox under Pull
      4. Click on the Select Pull-Update Fields link
      5. Select Act-On Lead Score
  4. Click Schedule to set when you would like the sync to occur.
  5. Click Save.

Repeat these steps for the other SugarCRM marketing lists you would like to keep in sync.

Standard Field Names

The Standard Field Names page allows you to define a standard set of field names you typically use in your Act-On lists. The set of field names can then be quickly accessed when creating and editing lists, creating form fields, and other areas in the application where field names can be selected.

To define your set of standard field names:

  1. Click on Contacts.
  2. Choose Standard Field Names
  3. Click Optimize for SugarCRM to pull in all of your custom and standard fields from your SugarCRM Lead and Contact entities into the field name

Remember: Custom fields rely on alignment between your CRM and Act-On. If these field names change in your CRM but are not updated in Act-On to match, syncs will fail going forward.

Push Lead Score

If you are pushing the lead score back to SugarCRM, the Score column needs to be updated prior to doing the sync. This can be done with the help of a list maintenance program.

  1. Hover over the list to be updated and, click the drop-down arrow.
  2. Choose Maintenance, and Set up Maintenance Program.
  3. Enter a name for the program, and click Add a Step.
  4. Choose Change Field Value.
  5. Enter a step name, choose the Act-On behavior score field as the update field, and then choose to Set the value to the Behavioral Score.
  6. Click Done and then click on the Only when clicking the Now button link to set up the schedule.
    • Set the schedule to be earlier than the sync you setup. For example, if the sync was to set to happen at midnight, make sure the behavior score update is finished prior to the sync.
    • Click Save, and then the Listing button to finish
    • Repeat these steps on any other lists that include the lead score

The list is now fully set up to sync. Its listing will show the SugarCRM icon on the left, the gear icon for the maintenance program, and calendar for the scheduled sync on the right.

Note: Before setting up the Hot Prospects Dashlet, you must first have a managed feature turned on in your account called PersonalizedFrom. To have this feature enabled, contact your CSM/Tech Support.
  1. Hover over your All Sugar CRM Leads list and click the down arrow.
  2. Choose Maintenance > Identify List Columns.
  3. Under Contact Owner Name use the drop-down to select Assign to.
  4. Click Save.
  5. Navigate to Contacts > Account Lists > Sales Prospects to select the lists as shown below.
  • Was this article helpful?

Have a question about this topic?

Ask the community!