This documentation refers to an older version of CiviCRM (3.4 / 4.0). View latest version.

Skip to end of metadata
Go to start of metadata
This page refers to CiviCRM 3.4 and 4.0, current STABLE version.

Documentation Search

CiviCRM 3.4 and 4.0 Documentation

Support and Participation

Developer Resources

CiviCRM books!

Make sure to check out the FLOSS Manual Understanding CiviCRM as well! You can also support this project by ordering a hard copy.

Or support us by buying an eBook or hard copy of Using CiviCRM from Packt Publishing.

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 should continue to work but if you need any help with API code you should trade up before asking for help


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:


Most entities support the following actions:




Insert one new record. (Note: If an "id" is specified, then an existing record will be modified.)


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);


Search for records


Search for records and return the quantity. (Note: In many cases the queries are limited to 25 so this may not always be accurate)


Fetch entity metadata, i.e. the list of fields supported by the entity


Search for records and return the first or only match. (Note: This returns the record in a simplified format which is easy to use)


Does a GET & Returns a single value - you need to also set $param['return'] => 'fieldname'


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 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.

  1. PHP
  2. REST interface
  3. AJAX Interface, to be called from javascript code
  4. Smarty interface to add more variable not available by default in the template
  5. 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).


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

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.

Results may be sorted within Smarty calls to the API just as any other, however the syntax needs to be altered slightly to account for Smarty's attention to periods ( . ) in variable names. Use option_sort in place of option.sort in this case. For example:

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.


$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


$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

Note that there are a few supported syntaxes

civicrm('Contact', 'Create', array('version' => 3, 'contact_type' => 'Individual', 'display_name' => 'BA Baracus', '' => array('url' => ''));

is the same as

civicrm('Contact', 'Create', array('version' => 3, 'contact_type' => 'Individual', 'display_name' => 'BA Baracus', '' => array('url' => ''));

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', '' => array('url' => '', ),'' => array('url' => '', ));


civicrm('Contact', 'Create', array('version' => 3, 'contact_type' => 'Individual', 'display_name' => 'BA Baracus', '' => array(array('url' => '', ), array('url' => '', )));

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

Custom data

There are a couple of ways to interact with custom data using the API.

  • There are three custom data api calls, CustomField, CustomGroup, and CustomValue
  • using the custom_N notation when doing an API call on an entity.

See this forum post for discussion of which is better:,21844.0/topicseen.html)


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


$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']

Legacy API documentation

  • None