Skip to content

APIv4 Changelog

This page lists major or breaking changes to APIv4 with each new release of CiviCRM Core. Other update notes can be found elsewhere:

CiviCRM 5.64

If using Workflow.render api (or the not-supported-for-external-use functions CRM_Core_BAO_MessageTemplate::sendMessage) the ids in the WorkflowMessage (model) properties (variously called 'values' or 'modelProps') now use consistent non-freudian casing. They are standardised on contactID rather than contactId etc. The tokenProperties still use freud-case (id rather than ID).

CiviCRM 5.54

5.54 Autocomplete action added

This API action is used with Entity Autocomplete inputs, which replace the APIv3-based EntityRef widgets.

CiviCRM 5.45

5.45 ManagedEntity trait added with export and revert actions

For details see managed entity and export action pull requests.

5.45 Contact::delete uses trash by default

For details see pull request and documentation on write actions and basic actions.

5.45 SortableEntity trait added with auto-weight management

For details see pull request.

5.45 Navigation entity treats permission field as array rather than string

For details see pull request.

5.45 RelationshipCache entity now has case_id column

For details see pull request.

CiviCRM 5.43

5.43 Only fields declared in getFields returned by default.

Every API must declare a getFields action to define what fields are returned; as of 5.43 this list is used more strictly: When using SELECT(*) or ommitting SELECT, only declared fields of type "Field" will be returned. See pull-request for details.

5.43 Virtual entities supported via event in Entity::get.

It's now possible to define ad-hoc or virtual entities without their own DAO. See pull-request for details.

CiviCRM 5.38

5.38 Implicit join syntax changed, old syntax deprecated.

As of 5.38 the API supports the syntax contact_id.display_name and the old contact.display_name is deprecated. See pull request for details.

CiviCRM 5.29

5.29 Added target_contact_id and assignee_contact_id to Activity.create in the API explorer.

Each can take an array of contact IDs. This feature existed before version 5.29.0 but was previously not discoverable in the explorer. For more information see the commit to CiviCRM Core.

5.29 Shortcut for setting checkPermissions e.g. Contact::get(FALSE)

For more information see the following pull request.

CiviCRM 5.23

5.23 $index param supports array input

CiviCRM 5.23 supports two new modes for the $index param - associative and non-associative array. See CiviCRM Core PR #16257

5.23 Converts field values to correct data type

The api historically returns everything as a raw string from the query instead of converting it to the correct variable type (bool, int, float). As of CiviCRM 5.23 this is fixed for all DAO-based entities. See CiviCRM Core PR #16274

5.23 Selects only relevant contact fields by default

The Contact entity in CiviCRM is divided into 3 major types: Individuals, Households and Organizations. Not all contact fields apply to all contact types, e.g. the sic_code field is only used by Organizations, and the first_name and last_name fields are only used by Individuals.

In CiviCRM 5.23 the schema has been augmented with metadata about which fields belong to which contact type, and Api4 now uses this metadata to select only relevant fields. E.g. fetching a household with the api will not return the first_name or organization_name fields as those will always be null.

5.23 Get actions support selecting fields by * wildcard

The select param now supports the * wildcard character for matching field names. See CiviCRM Core PR #16302.

5.23 Delete/Update do not throw error when 0 items found

For consistency across all "batch-style" actions that update/delete records based on a query, the Delete and Update actions now simply return an empty result if no matches are found to act upon. Previously they would throw an exception, which was similar to APIv3 behavior but inconsistent with other APIv4 batch actions and SQL in general. See CiviCRM Core PR #16374.