CiviCRM Public APIs

If you are writing any new code or fixing code that involves using the API you should use API v3. API v3 ships with CiviCRM 3.4 and 4.0 but you can backport apiv3 to an earlier code base very easily!

API v2 code is deprecated and doesn't work from the REST/Ajax interface anymore as of 4.1.2. It will be removed of civicrm 4.2

Resources

Our goal is to keep the main documentation for the API within locations that are closely tied to the code and functionality. This allows the API programmers to improve both code and documentation in tandem. The key resources are:

api explorer (visit /civicrm/ajax/doc/api#explorer on your installation) - see our screencasthttp://www.youtube.com/watch?hl=en&v=G_mLgR-rbGg&gl=US
php examples directory
code level documentation (Do not call these functions directly, but always use the civicrm_api wrapper)

Actions

Most entities support the following actions:

Action	Description
CREATE	Insert one new record. (Note: If an "id" is specified, then an existing record will be modified.)
DELETE	Delete one record. (Note: Requires an explicit "id". Note: if you want to skip the 'recycle bin' for entities that support undelete (e.g. contacts) you should set $param['skip_undelete'] => 1);
GET	Search for records
GETCOUNT	Search for records and return the quantity. (Note: In many cases the queries are limited to 25 so this may not always be accurate)
GETFIELDS	Fetch entity metadata, i.e. the list of fields supported by the entity
GETSINGLE	Search for records and return the first or only match. (Note: This returns the record in a simplified format which is easy to use)
GETVALUE	Does a GET & Returns a single value - you need to also set $param['return'] => 'fieldname'
REPLACE	Replace an old set of records with a new or modified set of records. (For example, replace the set of "Phone" numbers with a different set of "Phone" numbers.). Warning - REPLACE includes an implicit delete - use with care & test well before using in production
UPDATE	Update one or more fields for an existing record. (Note: CREATE with an "id" can also update an existing record; Update does a 'get' and a 'create' with id. It's mostly to work around occasional bugs and the preferred approach is to fix the bugs)

Ways to call the API

API v3 is available in five different environments. In each environment, the API uses the same names for entities, actions, and parameters, but the syntax is slightly different.

PHP
REST interface
AJAX Interface, to be called from javascript code
Smarty interface to add more variable not available by default in the template
CiviCRM drush module (in Drupal) - doesn't seem to work at the moment!

Most of the examples and API descriptions use the direct php call syntax. However, you can access all these APIs via other channels if you adapt the syntax (eg. the list of return variables is either a php array, several get parameters or a comma separated list).

Bindings

Here are basic examples of getting a contact using each method.

Bindings: PHP

Further examples are in the api/v3/examples folder in your install or in the svn repo. Note that the examples are all generated by the test suite. If there is something missing from the examples post on the API forum board and help us add it to the test suite. This may be a function or a field within that function.

Apparently it should no longer be necessary to include a call to civicrm_initialize as this is handled within api.php - but some ??old versions may still need it.

Binding from a standalone custom PHP script (Joomla)

Since a standalone script is not aware either of Joomla or CiviCRM, some initialization must be done in order to setup a "Civi-aware" environment.
Make sure to require the following files for that purpose

And to ensure a single instance of a connection to Civi, add the following line:

For ready-made examples, look in the directory shipped with CiviCRM installation that can be found at
/<USER_HOME>/administrator/components/com_civicrm/civicrm/api/v3/examples

Bindings: REST

Obviously you should substitute your site in! You can explore the syntax and options available using the api explorer (also on your site!)

You can call the REST interface, from another server via http.

Bindings: Smarty

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

Data Returned

The return from the api call is always an array. The api does some internal error checking and populates the array based on success or error.

Success

$result['is_error'] = 0

$result['version'] = 2 or 3 as appropriate

$result['count'] = number of records in the 'values' element of the $result array

$result['values'] = an array of records

Error

$result['is_error'] = 1

$result['error_message'] = An error message as a string.

Nested / Chained calls

It is now possible to do two api calls at once with the first call feeding into the second. E.g. to create a contact with a contribution you can nest the contribution create into the contact create. Once the contact has been created it will action the contribution create using the id from the contact create as 'contact_id'. Likewise you can ask for all activities or all contributions to be returned when you do a get. Some examples will explain

http://svn.civicrm.org/civicrm/branches/v3.4/api/v3/examples/ContactCreate.php http://svn.civicrm.org/civicrm/branches/v3.4/api/v3/examples/ContactGet.php

Note that there are a few supported syntaxes

civicrm('Contact', 'Create', array('version' => 3, 'contact_type' => 'Individual', 'display_name' => 'BA Baracus', 'api.website.create' => array('url' => 'Ateam.com'));

is the same as

civicrm('Contact', 'Create', array('version' => 3, 'contact_type' => 'Individual', 'display_name' => 'BA Baracus', 'api.website' => array('url' => 'Ateam.com'));

If you have 2 websites to create you can pass them as ids after the '.' or an array

civicrm('Contact', 'Create', array('version' => 3, 'contact_type' => 'Individual', 'display_name' => 'BA Baracus', 'api.website.create' => array('url' => 'Ateam.com', ),'api.website.create.2' => array('url' => 'warmbeer.com', ));

OR

civicrm('Contact', 'Create', array('version' => 3, 'contact_type' => 'Individual', 'display_name' => 'BA Baracus', 'api.website.create' => array(array('url' => 'Ateam.com', ), array('url' => 'warmbeer.com', )));

the format you use on the way in will dictate the format on the way out.

Currently this supports any entity & it will convert to 'entity_id' - ie. a PledgePayment inside a contribution will receive the contribution_id from the outer call

Working with custom data on entities

Custom data attached to entities is referenced by custom_N where N is the unique numerical ID for the custom data field.

To set a custom field, or get entities with custom fields of a particular value, use:

$param['custom_N'] => 'value';

To return custom data for an entity, pass a param like the following:

$param['return.custom_N'] => 1;

Special fields

There are some fields you can pass into API v3 that change the behaviour

Sequential

$params['sequential'] =1; will cause the returned array to be sequentially indexed rather than by the entity id.

Without sequential

$result= civicrm_api('UFMatch','Get', array('version' =>3, 'uf_id' => $user->uid);
$contactid=$contact['values'][$result['id']]['contact_id'] );

With sequential

$result= civicrm_api('UFMatch','Get', array('version' =>3, 'uf_id' => $user->uid, 'sequential' => 1);
$contactid=$result['values'][0]['contact_id'] );

Note that a single record is returned in this example - whenever a single record is returned the entity_id of that record should be in $result['id']