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:
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.
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.
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.
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
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.
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:
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', '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', ));
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
There are a couple of ways to interact with custom data using the API.
See this forum post for discussion of which is better: http://forum.civicrm.org/index.php/topic,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;
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.
$result= civicrm_api('UFMatch','Get', array('version' =>3, 'uf_id' => $user->uid);
$result= civicrm_api('UFMatch','Get', array('version' =>3, 'uf_id' => $user->uid, 'sequential' => 1);
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']