Skip to content

APIv4 Option Lists

Some fields in CiviCRM are linked to an option list (aka Pseudoconstant). These fields are typically shown to the user as checkboxes, radios, or a dropdown-select of options from the pseudoconstant list.

The API provides tools for working with such fields; so that downstream developers do not need to translate between database values and option properties.

Option list properties

All option lists consist of at least:

  • id: The value stored by a field
  • name: Non-changing string identifier
  • label: Translatable label shown to user

Some option lists also contain

  • description: Text description shown to the user in select2 lists
  • abbr: Abbreviation (used with country and state/province lists)
  • icon: CSS class used to produce an icon for an option
  • color: Hex value of the color for an option

Which fields have option lists?

To find out which fields have option lists for a particular entity, use the getFields action from the API or API Explorer, e.g.

civicrm_api4('Contact', 'getFields' [
  'where' => [['options', '!=', FALSE]],
])
This will return a list of all fields for a given entity (in this example, "Contact") which have an option list.

Retrieving an option list

If you need to retrieve the full option list for a field, use the getFields action and set the loadOptions parameter to an array of the above properties you would like to retrieve. Try it in the API explorer, e.g.

civicrm_api4('Contact', 'getFields' [
  'where' => [['name', '=', 'contact_type']],
  'loadOptions' => ['name', 'label', 'description'],
])->first();
This will load information about the contact_type field including the list of available options (names will be ['Individual', 'Household', 'Organization'], labels will be localized translations if the site is not in English).

Tip

Unless you are building a form and need to render an option list for the user to select, in most cases you will not need to query getFields to e.g. match option ids to labels. The syntax below can automatically perform such transformations.

Option transformations

When reading or writing data from the API, a special suffix tells the API to transform between option ids and other properties. For example:

Writing

Activity::create()
  ->addValue('activity_type_id:name', 'Meeting')
  ...

Using this syntax saves you from needing to look up the id of an activity type. It also makes your code more portable, as option ids can change from one database to another, but names are consistent.

Reading

Get operations use the same syntax to reverse the lookup and transform an option id to another property.

Activity::get()
  ->addSelect('*', 'activity_type_id:label', 'activity_type_id:icon')
  ...

This tells the API to return all fields (*) plus the label and icon of the activity type, giving the data needed for a user-facing display.

Option Lists or Joins

The syntax for option transformations looks very similar to implicit joins (the difference being a colon instead of a dot). Your choice of which to use depends on the field. For example, the Contact gender_id field has an option list but not a foreign key, so you must use the option syntax (gender_id:label). But the Event campaign_id field has a foreign key instead of an option list, so you would use a join (campaign_id.title).