What is the correct way to work with custom data in the API?

Question

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.

Answer 1

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:

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

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

Answer 2

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

Answer 3

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

• API Examples
• API Tests

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.

Answer 4

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.

Example:

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