Skip to end of metadata
Go to start of metadata

 

Use the API explorer to see the syntax and the result (visit /civicrm/ajax/doc/api#explorer on your installation OR see Xavier's youtube video).

The rest interface works like the ajax interface, with one major difference: each call requires an api_key (user key) & key (site key) parameter. And there has to be a user with that api_key (see below about creating API keys for users) that has sufficient permissions (Access AJAX API, and presumably more depending on which entity you want to access). Check the API Security page for more info.

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. Although being able to handle both GET and POST for the param. Please use POST, it works for get actions and is mandatory for all the actions that alter (create, modify or delete) data.

It has been rewritten to handle the new API v3 and expose the complete API Reference to your external service.

For security whenever possible use SSL when accessing this interface.

To call the API use the URL:

for instance, the first call is to get a list of contacts (first 25)

The second way to call REST interface from your browser is through an ajax function using CRM.api (as XHR, not as a regular page for security reasons) that uses this url below.

This method validates the permissions of the logged in user before returning any data.  For example, if the logged in (or anonymous) user does not have 'CiviCRM: access AJAX API' permission enabled then the REST call will not return the requested data. Other permissions may be necessary depending on the entity and action types. Permissions can be granted for anonymous users or other user roles via the CMS permissioning interface, or via a custom php hook implementation of hook_civicrm_alterAPIPermissions.

Functions offered via the rest interface

Conventions

Throughout this documentation the commands will be expressed:

 All commands should be prefaced with (don't forget to append the site_key and api_key parameters for this method):

Or through through an ajax function using CRM.api (as XHR, not as a regular page for security reasons) that uses this url below

Setting up to use the REST API

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

  1. You need to know your site key which can be found in the civicrm.settings.php file labelled CIVICRM_SITE_KEY.
  2. You will need to enter an API key for every user that will be allowed to use the REST interface. (See below)

Creating API keys for users

There are three methods of creating an API key for an individual user

Manual Method

Enter the key directly in the database table civicrm_contact into the field api_key using your database tool. That would normally be phpmyadmin, MySQL Workbench or something like that.

If you are using Drupal, you may want to check for sure which CiviCRM contact ID you need to modify - to make sure proper Drupal user gets the permissions. To find out Drupal user ID match to CiviCRM contact ID, check the table civicrm_uf_match

If you know the ID of the contact you want to update, the query would look like this:

Remember that this user has to have "Access AJAX API" permission and possibly others (see API security other permissions)

API Key Extension

There is now an extension available called API Key at https://civicrm.org/extensions/api-key that makes the setting of API keys for users much easier.

Once installed, an 'API Key' tab will be available on contact screens for which you are authorized to manage the API key for this contact. You are authorized either if the contact if yourself, or if you are an administrator with the 'edit all contacts' permission.

You can then add an API key, Edit an exiting API key (with either manual input or an auto-generate feature) or Delete an API key (by setting it's value to blank).

Utilizing the API Explorer

See this StackExchange thread that @Joe Murry put together in such an expert way:

http://civicrm.stackexchange.com/questions/9945/how-do-i-set-up-an-api-key-for-a-user

options parameters

The options parameters listed in Using the API#Options are passed in PHP as an array. In a REST URI, 

PHPREST
civicrm_api('GroupContact','get', array(
  'version' => 3,
  'group_id' => 2,
  'options' => array(
    'limit' => 25,
    'offset' => 50,
  ),
));
/civicrm/extern/rest.php?entity=GroupContact&action=get&group_id=2&options[limit]=25&options[offset]=50

Chaining parameters

Chaining can be used via REST. The parameter format is for example: api.Email.replace[values][params][email]=zzz@yyy.com or api.Website.replace[values][params][url]=http://www.example.com

Example shown below. However, you will want to submit a create call via POST and you may need to url encode the parameter values.

PHPREST
civicrm_api('Contact','create', array(
  'version' => 3,
  'first_name' => 'Joe',
  'last_name' => 'Blow',
  'api.Email.replace' => array(
    'email' => 'joeblow@example.com',
    'on_hold' => 1,
  ),
));
/civicrm/extern/rest.php?entity=Contact&action=create&group_id=2&api.Email.replace[values][params][email]=joeblow@example.com&api.Email.replace[values][params][on_hold]=1

login

You do not need to login to use the /civicrm/extern/rest.php method. Each call requires the user having their own credential (key and api_key) and each call to the api is independent, as the REST gods intended. 

Contact Search

To search the contact database use the contact get 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 list of contacts provide no parameters (it has an implicit limit to 25), so entity=contact&action=get.

 

 

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 and should specify the fields you want returned (the contact id is always returned):

  • return=sort_name,country,email,...

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 :

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

See setup above.

Retrieving data

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/v3. In this file I have this code:

The result will be:

Labels
  • None
  1. Mar 29, 2009

    I'm just getting my head around this but it seems worth mentioning that you need to use the site key as described here

    site key docs

    http://mysite.com/sites/all/modules/civicrm/extern/rest.php?q=civicrm/contact/search&key=sitekey

    and to configure the user you plan to use with an api key - (via mysql in the civicrm_contact table). I think anything will do

  2. Jun 28, 2013

    You CANNOT call ajax from a browser as stated above or you will get: SECURITY ALERT: Ajax requests can only be issued by javascript clients, eg. CRM.api()."}

    1. Jun 28, 2013

      fixed. thx

  3. Jul 22, 2015

    Hello,

    I'm new to CiViCRM. I want to fetch events which are created in CiViCRM which is hosted on another server. So basically I want to fetch CiViCRM data from one individual site to my site. I don't know that which are the ways to do it and which is the best one. But I think Rest option would be good if I'm not wrong. I'm not able to find any similar example which is near to my task. All I don't understand that how should I use my rest url with code:

     

    1) Option 1:

    $api = new civicrm_api3(array ('server' => 'http://localhost/abc',

    'api_key'=>'123456789',
    'key'=>'123xyzABC'));

       

    2) Option 2:

    $contactxml = simplexml_load_file("http://localhost/abc/sites/all/modules/civicrm/extern/rest.php?entity=contact&action=get&key=<site key>&api_key=$apikey&last_name=Koot");
    foreach ($contactxml->children() as $contact) {
        $display = $contact->display_name;
    }

     

    Is there any other options. I want to go for option 1 if that is possible. And I want response in JSON if possible. 

    Any help wound be appreciated.   

    Thanks

     

    1. Jul 22, 2015

      You are more likely to get a response if you ask on our SE site http://civicrm.stackexchange.com/ ( Sorry I am not a techie and can't help you.)

      1. Jul 22, 2015

        Thanks for your reply, I have already seen that link.

        All I don't understand is the code.

        As per this link: http://wiki.civicrm.org/confluence/display/CRMDOC42/REST+interface

        First thing is to login:

        $test = simplexml_load_file("https:///sites/all/modules/civicrm/extern/rest.php?q=civicrm/login&name=Erik Hommel&pass=&key="); foreach ($test->children() as $kids) { $apikey = $kids->api_key; $sessionid = $kids->PHPSESSID; }

        Query: But what should be the value of "name" and "pass" parameters? Are those the credentials of a Drupal user with admin role (which has permission to access CIViCRM API) OR any contact from CiViCRM?

        By the way I have tried above but it is not giving anything in response. Not even any error.

  4. Jul 22, 2015

    @Joanne Chester

    Thanks for your reply, I have already seen that link.

    All I don't understand is the code.

    As per this link: http://wiki.civicrm.org/confluence/display/CRMDOC42/REST+interface

    First thing is to login:

    $test = simplexml_load_file("https:///sites/all/modules/civicrm/extern/rest.php?q=civicrm/login&name=Erik Hommel&pass=&key="); foreach ($test->children() as $kids) { $apikey = $kids->api_key; $sessionid = $kids->PHPSESSID; }

    Query: But what should be the value of "name" and "pass" parameters? Are those the credentials of a Drupal user with admin role (which has permission to access CIViCRM API) OR any contact from CiViCRM?

    By the way I have tried above but it is not giving anything in response. Not even any error.