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
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:
Creating API keys for users
There are three methods of creating an API key for an individual user
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:
The options parameters listed in Using the API#Options are passed in PHP as an array. In a REST URI,
Chaining can be used via REST. The parameter format is for example:
Example shown below. However, you will want to submit a create call via POST and you may need to url encode the parameter values.
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.
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
For a list of contacts provide no parameters (it has an implicit limit to 25), so entity=contact&action=get.
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.
You can search by nearly any field in the database.
You can and should specify the fields you want returned (the contact id is always returned):
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.
Returns the contact ID for the new contact, or an error.
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[email] along with email[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.
Returns the contact ID for the contact, or an error.
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.
Returns groups that match to search conditions. The references to where_clause, select_tables, and where_tables are primarily for smart groups.
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.
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.
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
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:
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.
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:
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: