Using the API with CiviCRM
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
- CiviCRM (minimum version 4.2.6)
- PHP-Curl library
All the directories in these instructions are relative to the CiviCRM root directory (such as /var/www/civicrm)
- Create an API user using the "Manage Users" menu in your Simplelists account
- Install CiviCRM normally as per its installation instructions
- 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
- Silcivi.php in
- Create a custom templates directory (such as
- 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>
- 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
- 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>;
sites/default/civicrm.settings.phpand check that
CIVICRM_SITE_KEYhas 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.
- 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