I always seem to struggle to find a concise way of working with custom data via the API. I know that something like...

$updateParams = array('version' => 3, 'contact_id' => $contact_id, 'custom_160' => $badges);
$result=civicrm_api('contact', 'update', $updateParams);

...works for some but not all entities, so I presume that I'm meant to be using the CustomValue API, but whenever I do, my code looks v. clunky / doesn't work / I resort to SQL in frustration. If anyone has a concise example or two of CustomValue in use that would be most appreciated.

4 Answers 4


As of CiviCRM 4.6, the api explorer is like 1-stop-shopping for browsing, building and testing api calls.

  • You can start on the "Examples" tab to see how custom values are generally done: Api Examples

  • If you want more detailed explanation of how it works, try the "Code Docs" tab: Api Docs

  • And finally, the Explorer tab lets you browse available params and will write the php/javascript/rest/cli code for you: Api Explorer


Note that 'update' action is deprecated and replaced by 'create'. If you give the primary fields in the params (usually id but it's entity_id+custom_xx in your case), you will automatically get an update.

Also note that there are examples of api uses in https://github.com/civicrm/civicrm-core/tree/master/api/v3/examples. It's very helpful to see what are the possibilities and what are the results we can expect.

Last, you could use civicrm_api3 instead of civicrm_api so you don't have to define the version in the params, which i personnaly found awkward.

Having that say, I guess the best way to do what you want would be :

$params = array(
  'custom_160' => $badges,
  'entity_id' => $contact_id,
try {
  $result = civicrm_api3('CustomValue', 'create', $params);
catch (CiviCRM_API3_Exception $e) {
  // Handle error here if you want

If you are pretty sure of what you are doing and want a concise way, you could do :

$params = array('custom_160' => $badges, 'entity_id' => $contact_id);
$result = civicrm_api3('CustomValue', 'create', $params);

My first stopping points on how to work with CiviCRM API are usually -

In those directories you'll find examples for most API usage.

$params = array(
  'first_name' => 'abc3',
  'last_name' => 'xyz3',
  'contact_type' => 'Individual',
  'email' => '[email protected]',
  'custom_123' => 'foo',
try {
  $result = civicrm_api3('CustomValue', 'create', $params);
catch (Exception $e) {
  // uhoh

Looking up custom field IDs in API calls can require a bit of additional code beforehand.


If you want to get the CustomValue of other entities than Contact, you need to specify the entity_table. I think it could be good to have this in the api examples because it is indeed not there and very hard to find this info.


$result = civicrm_api3('CustomValue', 'get', array(
  'sequential' => 1,
  'entity_table' => "Participant",
  'entity_id' => 23,

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.