Navigation ›

Using the API with CiviCRM

Functionality

The CiviCRM API allows syncronisation both ways between Simplelists and CiviCRM. For synchronisation from CiviCRM to Simplelists it functions in the following manner:

  • When a contact is created in CiviCRM, the contact is created in Simplelists
  • When a contact is updated in CiviCRM, the contact is updated in Simplelists
  • When an email address or contact is deleted or put on-hold in CiviCRM, the associated email adddress(es) are deleted from Simplelists
  • When a contact is created in CiviCRM, an existing Simplelists contact with the same email address will be updated
  • CiviCRM will be taken off hold
  • For Multiple Lists, if a group exists in both Simplelists and CiviCRM, then the group membership will be syncronised from CiviCRM to Simplelists
  • An optional CiviCRM group can be specified, in which case any synchronisation from CiviCRM will only take place if the contact is a member of that group. If the contact is added or removed from the group, then the contact will be added or removed from Simplelists

The CiviCRM API functions in the following manner (not yet implemented):

  • When a contact is created in Simplelists, the contact is created in CiviCRM
  • When a contact is updated in Simplelists, the contact is updated in CiviCRM
  • When an email address or contact is deleted in Simplelists, the associated email adddress(es) are marked as on hold in CiviCRM
  • When a contact is created in Simplelists, an existing CiviCRM contact with the same email address will be updated
  • If an email address in CiviCRM is on hold, and the same email address is added to Simplelists, the email address in CiviCRM will be taken off hold
  • For Multiple Lists, groups will be created in CiviCRM reflecting the Simplelists lists membership
  • An optional CiviCRM group can be specified, in which case:
    • New contacts added to Simplelists will be automatically be added to the CiviCRM group
    • Modifications to contacts in Simplelists will only be replicated to CiviCRM if the contact is in the group

Prerequisites

  • CiviCRM (minimum version 4.2.6)
  • PHP-Curl library

Installation

All the directories in these instructions are relative to the CiviCRM root directory (such as /var/www/civicrm)

  1. Create an API user using the "Manage Users" menu in your Simplelists account
  2. Install CiviCRM normally as per its installation instructions
  3. Download the Simplelists CiviCRM module. Unzip the files and place them in your CiviCRM installation as follows:
    • silcivi.class.php, silcivi.info and silcivi.module in sites/all/modules
    • Silcivi.php in sites/all/modules/civicrm/api/v3
  4. Configure the API in CiviCRM:
    • Create a custom templates directory (such as sites/all/civicrm_templates.
    • Configure CiviCRM to use this as the custom template directory (Administer → System Settings → Directories). Enter the created directory in the Custom Templates configuration option (using the other directory configurations as an example). Be sure to include a trailing slash!
    • Create a file called silcivi_settings.xml in that directory with the content as follows. Replace "apiuser" with the API user created in the first step, and "apipassword" with the password for the account. The SimpleApiClientUser and SimpleApiClientPass must be obtained from Simplelists Support.
    • <?xml version="1.0" encoding="UTF-8"?>
      <Setting>
      <SimpleApiUser>apiuser</SimpleApiUser>
      <SimpleApiPass>apipassword</SimpleApiPass>
      <SimpleApiClientUser>apiclientuser</SimpleApiClientUser>
      <SimpleApiClientPass>apiclientpass</SimpleApiClientPass>
      <SimpleApiTokenUrl>https://www.simplelists.com/api/token.php</SimpleApiTokenUrl>
      <SimpleApiResourceUrl>https://www.simplelists.com/api/api.php</SimpleApiResourceUrl>
      </Setting>
    • The following optional parameters can also be used. SimpleGroup specifies a group for which synchronisation will only take place. SimpleApiDebug shows debug information when making API calls.
    • <SimpleGroup>simplelistsgrp</SimpleGroup>
      <SimpleApiDebug>true</SimpleApiDebug>
      
  5. Navigate back to Drupal and enable the Simplelists module using the Modules menu (check the box next to the module name and click Save Configuration).
  6. At this stage your Simplelists account will be kept updated by CiviCRM. To enable the reverse to happen as well, carry out the following instructions:
  7. Create and configure a Drupal user. This user will be used by Simplelists to make changes to CiviCRM:
    • Login to Drupal and create a user (People → Add user). The user will need at least permissions to modify members in CiviCRM. By default, only an Administrator can do this.
    • Choose a random API key that will be used to authenticate the user. This should be a completely random string of characters, such as SAQbqJ1FKlKZ5Iav
    • Navigate back to CiviCRM and locate the user that you have just created (it should have been automatically added to CiviCRM). Open the user's details in CiviCRM and locate the contact's "CiviCRM ID".
    • You will now need to manually set the API key for this user, which can only be done manually: using phpMyAdmin, or by accessing the database directly, run the following SQL command against the CiviCRM database (using the ID and API key that you just noted): update civicrm_contact set api_key='<API key>' where id=<CiviCRM ID>;
  8. Open the file sites/default/civicrm.settings.php and check that CIVICRM_SITE_KEY has been set. It should have been nominated a value automatically. This is the Site Key; make a note of it or choose a new value.
  9. Your Simplelists account now needs to be configured to use your CiviCRM installation. Contact Simplelists Support with the following information:
    • The URL of your CiviCRM installation
    • The Site Key
    • The username and password of the CiviCRM user that you created for the API
    • The API Key that you created for this user
Blue image background