REST interface

One way of accessing civicrm from an external site is the rest interface.  It can return xml or json formatted civicrm data, via simple html requests.  It was developed initially by Aaron Crosman, from American Friends Service Committee to synchronise datas between civicrm and an external CMS. The rest interface has access to the complete CiviCRM Public APIs.

For security whenever possible use SSL when accessing this interface.

To call the API with a browser just use:

for instance, the first call is to authenticate

You can also call the rest interface from your browser (as used by more and more of the ajax functions):

Functions offered via the rest interface

Conventions

Throughout this documentation the commands will be expressed:

 All commands should be prefaced with:

Updated to work in your environment.

The parameters (key or PHPSESSID) are omitted above but at least one is are required. See http://wiki.civicrm.org/confluence/display/CRMDOC/Command-line+Script+Configuration for instructions on how to set up your site key.Get the CIVICRM_SITE_KEY value from your civicrm.settings.php file and append it to the url as follows:

&key=myCiviCRMSiteKey

You will also need to set up api_key values in the database for each user authorized to access the REST api. To do this you can temporarily reverse the commenting in the following lines in CRM/Utils/REST.php (around 102-103 in version 3.0alpha1) from:

        // CRM_Core_DAO::setFieldValue('CRM_Contact_DAO_Contact', $result[CRM:0], 'api_key', sha1($result[CRM:2]) );
        // $api_key = CRM_Core_DAO::getFieldValue('CRM_Contact_DAO_Contact', $result[CRM:0], 'api_key');
        return self::error("This user does not have a valid API key in the database, and therefore cannot authenticate through this interface");

to:

        CRM_Core_DAO::setFieldValue('CRM_Contact_DAO_Contact', $result[CRM:0], 'api_key', sha1($result[CRM:2]) );
        $api_key = CRM_Core_DAO::getFieldValue('CRM_Contact_DAO_Contact', $result[CRM:0], 'api_key');
        // return self::error("This user does not have a valid API key in the database, and therefore cannot authenticate through this interface");

and then login each API user account once before restoring the commenting of these lines to their original state.

login

Command

Login starts the PHP session and generates a key used for future commands.  When testing in a browser the PHP session will be automatically maintained, but when writing your own code you will have to maintain the session id yourself.  You will need to provide the api_key along with the CIVICRM_SITE_KEY from civicrm.settings.php for all other commands.

Response

If you don't have the PHPSESSID key you need to apply a patch

Contact Search

To search the contact database use the contact search commend. Given with no parameters it will return all contacts in the database. Optionally you can add search parameters like those in the search form. The parameter names should match the name of the field you wish to search. For example if you which to search by last name the parameter name is last_name

Command

For a complete list of contacts provide no parameters beyond the login key.

Response

Command (search by email)

To search the database based on email, you add a parameter to query string:

Response (search by email)

Returns a list of contacts with matching email addresses.

Selection criteria

You can search by nearly any field in the database.

• contact_id=XXX
• country=<name>
• contact_type= (Individual, Household,Organization)
• ....

Returned fields

You can specify the fields you want returned (the contact id is always returned):

• return[CRM:sort_name]=1
• return[CRM:country]=1
• return[CRM:email]=1
• ...

Create Contact

To insert a new contact into the database use parameter names like in search. Please Note: contact_type must be passed as a parameter when creating a contact.

Command

Response

Returns the contact ID for the new contact, or an error.

Update Contact

The API allows the add command to update a contact as well as add them. To update a contact the command is the same, with the exception that you must add the contact_id parameter, with the ID of the contact you would like to update.

Please Note: contact_type must be passed as a parameter when updating a contact.

Note: while email works as a parameter key to create a contact, email[1][email] along with email[1][location_type_id] is a more appropriate form if you want to update a contact's email. In this example, we're updating the e-mail address for the "Home" location type.

Command

Response

Returns the contact ID for the contact, or an error.

Search Groups

To search for groups use the group get command. It's actually not part of the current version of CiviCRM, but the code was easy to write, and once testing is complete I'll submit the patch to the project.

Command

Response

Returns groups that match to search conditions. The references to where_clause, select_tables, and where_tables are primarily for smart groups.

Create Group

Create a new group. There are several parameters that can be edited through the API, but some would be hard to use (like writing SQL clauses in the URL). If the is_active parameter is missing the group will not be enabled by default. If the group is not active it will not come up in searches with the get command.

Command

Response

Returns the ID of the new group, or an error.

Add user to Group

User the group_contact functions to add a user to a group.

Command

Response

Returns how many of the requested IDs were added (not sure how to ask for more than 1), and the total count in the group.

 Search related contacts

You need to apply this patch on the 2.11. and below http://issues.civicrm.org/jira/browse/CRM-3823

Command

Updating custom fields

where n is the fid of the custom field (the field "id" of the "civicrm_custom_field" SQL table).

If the custom field has multiple values:

Response

Returns the contacts related to contact id <ID>

 ? Works fine with json=1 but doesn't with XML ?!? Can someone test and confirm ?

Format of the results

By default, the result in in XML:

 but by adding json=1 as an extra parameter, you get :

Improvements and expansion

This is a work in progress and a place to discuss further improvement. For instance, we'd like to have a truly rest interface (without the need to call a login method first). The idea whould be to get a long non guessable unique ID that can be used directly in all the functions.

Simple example of using the REST interface

The REST interface can be used to get, create or update data in CiviCRM on another server, using the standard API. This is a simplified example I have used to test the basics for my project. 

The basic requirement for my project is that data of individuals has to be synchronized between a Java/Oracle application, a website and CiviCRM. To be able to achieve that, both the Java/Oracle application and the website use the REST interface to call my wrapper API, which in its turn uses the standard API's to get, create or update the CiviCRM database.

Set Up

Before the REST interface can be used, two things have to be set up:

1. You need to be sure a site key is set up for your site. See http://http://wiki.civicrm.org/confluence/display/CRMDOC32/Command-line+Script+Configuration on how to set up your site key.
2. You will need to enter an API key for every user that will be allowed to use the REST interface. You have to do that in the database (table civicrm_contact, field api_key) using phpmyadmin, MySQL Workbench or something like that.

Log In

Whenever you want to use the REST interface, your first call always has to be the log in with an authenticated user with an API key. The code from my calling server to perform the login function and retrieve the api_key and PHPSESSID that is returned by the REST interface:

Retrieving data

Once you have logged in, the standard API's can be used to create, update or get data. In the example code I retrieve the display_name of a contact using the contact_get API:

Sending information

Actually in my project I am on the sending side. The other applications/sites call the API with the REST interface, and I have my own wrapper function that sends data out. A basic example of this situation:

I have created a PHP file called dgwcontact and placed in the folder <your root>/sites/all/modules/civicrm/api/v2. In this file I have this code:

The result will be: