usage.md

API Usage

Every API call consists of three elements: the entity, action, and parameters. For example, consider a few commonly-used entities along with the supported actions and parameters:

Entity	Description	Actions	Parameters
Contact	An individual, organization, or house-hold.	create get delete	contact_type nick_name preferred_language
Activity	A phone call, meeting, or email message. that has occurred (or will occur) at a specific date and time	create get delete	activity_type_id source_contact_id assignee_contact_id
Address	A street-address related to a contact.	create get delete	contact_id, street_address city state_province_id country_id

(For full, up-to-date details about specific entities and parameters, use the API Explorer.)

The API is available in many different environments (such as PHP, REST, and Javascript), and the notation differs slightly in each environment. However, if you understand the canonical notation, then other environments will appear as small adaptations.

Canonically, an API call is processed by the API kernel. The $entity, $action, and $params are passed as inputs, and an associative-array is returned as output.

$result = Civi::service('civi_api_kernel')->run('Contact', 'get', array(
  'version' => 3,
  'first_name' => 'Alice',
  'last_name' => 'Roberts'
));

The result of a successful API call typically looks like this:

array(
  'is_error' => 0,
  'version' => 3,
  'count' => /* number of records */,
  'values' => /* array of records */,
)

The result of a failed API call typically looks like this:

array(
  'is_error' => 1,
  'error_message' => /* a descriptive error message */,
)

!!! note A few specialized actions like getsingle or getvalue may return success in a different format.

PHP (civicrm_api3)

This is the most common way to call the API.

try {
  $contacts = civicrm_api3('Contact', 'get', array(
    'first_name' => 'Alice',
    'last_name' => 'Roberts',
  ));
}
catch (CiviCRM_API3_Exception $e) {
  $error = $e->getMessage();
}
printf("Found %d item(s)\n", $contacts['count']);

This format matches canonical format almost exactly, with a few improvements for usability:

• The function civicrm_api3() is easier to remember.
• The version => 3 parameter is not required.
• Errors are reported as PHP exceptions. You may catch the exceptions or (by default) allow them to bubble up.

Note: If you're writing a Drupal module, a Joomla extension, a WordPress plugin, or a standalone script, then you may need to bootstrap CiviCRM before using the API. See the examples in [Bootstrap Reference].

Bootstrap Reference

PHP (class.api.php)

CiviCRM v3.4 introduced an object-oriented API client, class.api.php. This class can be used locally or remotely to invoke APIs, as in:

require_once 'your/civicrm/folder/api/class.api.php';
$api = new civicrm_api3(array(
  // Specify location of "civicrm.settings.php".
  'conf_path' => 'your/sites/default',
));
$apiParams = array(
  'first_name' => 'Alice',
  'last_name' => 'Roberts',
);
if ($api->Contact->Get($apiParams)) {
  //each key of the result array is an attribute of the api
  echo "\n contacts found ".$api->count;
}
else {
  echo $api->errorMsg();
}

If you call the API in the object oriented fashion, you do not have to specify 'version' as a parameter.

The object-oriented client can connect to a local or remote CiviCRM instance. For details about connection parameters, see the docblock in class.api.php.

REST

For external services:

http://www.example.com/sites/all/modules/civicrm/extern/rest.php
  ?api_key=t0ps3cr3t
  &key=an07h3rs3cr3t
  &json=1
  &debug=1
  &version=3
  &entity=Contact
  &action=get
  &first_name=Alice
  &last_name=Roberts

For sessions already authenticated by the CMS (e.g. AJAX)

http://www.example.com/civicrm/ajax/rest
  ?json=1
  &debug=1
  &version=3
  &entity=Contact
  &action=get
  &first_name=Alice
  &last_name=Roberts

Obviously you should substitute your site in! You can explore the syntax and options available using the API Explorer.

Please note that the REST interface is subject to API Security.

For more details, see REST interface. 

AJAX

CRM.api3('entity', 'action', [params], [statusMessage]);

For more details, see [AJAX Interface].

AJAX Interface

The AJAX interface is automatically available for web-pages generated through CiviCRM (such as standard CiviCRM web-pages, CiviCRM extensions, and custom CiviCRM templates).

The AJAX interface could be made available to other parts of the same website (e.g. a drupal module or wordpress widget) by calling CRM_Core_Resources::singleton()->addCoreResources() from php. Please note that the AJAX interface is subject to API Security and Same Origin Policy. To use it from an external site or application, see REST interface documentation.

Smarty

{crmAPI var="myContactList" entity="Contact" action="get" version="3" first_name="Alice" last_name="Roberts" }
Found {$myContactList.count} item(s).

The smarty call is to add extra information, therefore create or delete actions don't make sense in this case.

For more details, see Smarty API interface.

Command line

drush

To run on the default Drupal site:

drush civicrm-api contact.get first_name=Alice last_name=Roberts

To run on Drupal multisite, specify the site name:

drush -l www.example.com civicrm-api contact.get first_name=Alice last_name=Roberts

wp-cli

wp civicrm-api contact.get first_name=Alice last_name=Roberts

cv

cv api contact.get first_name=Alice last_name=Roberts

API Security

API has security mesasures built in depending on the way the API is called that can also be turned off or on. API Permissions are also able to be altered via hook. More information on API Security can be found in the Security Documentation.

API Lookups by Username

You can use a CMS username in lieu of a contact ID by prefacing it with @user:. For instance, if the user "james" has a CiviCRM contact ID of 123, these statements are identical:

cv api contact.get id=123
cv api contact.get id=@user:james