API Overview

Scope and Definitions

CiviCRM API's will be invoked by external modules exclusively via PHP function calls within the CMS framework. All input should be formatted as an array. In general, CiviCRM API's will return an array to the caller.

Resources and Tips for API Coding Due to the rapid development environment of the platform it is best to verify object properties by reviewing the current schema, or by checking your installation's SQL table layouts. Check out the API Tests directory from our public sourcecode (SVN) repository. This has a large number of API unit test functions, which are very useful in demonstrating basic usage/invocation syntax for each API. Refer to the growing library of snippets for working examples.

Several APIs will accept a variable set of input parameters. In these cases, an associative array of name/value pairs with the name $params is used. This approach is well-suited to the CiviCRM APIs which often offer a large number of optional input properties. It avoids reliance on the ordinality of these parameters (the caller only needs to define in the array the inputs needed for a particular case) - and streamlines subsequent additions of new frequently used parameters (by not forcing them to the end of a long list of fixed-order input values).

<?php
$params = array (
   "email"  => "paula@foobar.org",
   "first_name" => "Paula",
   "last_name" => "Stonesmith"
);
?>

Date Formatting Use the following format when passing date or date-time values as input parameters: Date: YYYYMMDD Date + Time: YYYYMMDDHHMMSS Use 24 hour clock for hours.

Several APIs provide the ability to return a selected subset of available data. For example, when calling civicrm_contact_search(), all the return properties should be prefixed with 'return.'. If array( 'return.home_url' => 1 ) will be passed then returned result will have only home_url values for the searched contacts. For APIs which use this feature, the default NULL value will cause a default set of properties to be returned. Default return properties for each data object are defined in the CiviCRM ERD.

Handling Large Data Sets All CRM APIs which have the potential to return large data sets give you the ability to limit the number of records returned using the $offset and $row_count parameters. Use them to implement paging functionality as shown in this code sample for paging through search results. When retrieving larger data sets, always use the $returnproperties parameter to request only the subset of properties needed. This will increase efficiency in terms of speed and memory utilization.

Permissioning for APIs

All requested API transactions will be evaluated based on the permissions of the currently logged in User. An 'access denied' error will be returned if the user role does not have sufficient permission for the requested operation in relation to the affected data object.

For additional details regarding CiviCRM and permissioning check:
Permissions Overview
Default Permissions and Roles

CiviCRM 'Contacts' and Drupal 'Users' (implementation of hook_user)

When the CiviCRM module is enabled, the relationship between contacts and users is: "Every user record will have a corresponding contact record. Contact records may or may not have a corresponding user record."

The CiviCRM module implements functionality for hook_user insert and update 'ops' (actions) in order to maintain this rule. CiviCRM Hooks

Error Handling

CiviCRM API's will return an error array in response to error or warning cases. Returned object can be tested for errors or warning conditions. For example:

if ( civicrm_error ( $result )) {
  return $result['error_message'];
} else {
  echo 'Contact Deleted Successfully ...';
}

The CRM error object is derived from PEAR_ErrorStack (defined in PEAR.php). For more information, see:

http://pear.php.net/package/PEAR/

Specific error messages and error codes will be added to this API documentation in a subsequent revision.