Skip to content

APIv4 Actions

With a few exceptions, most API Entities support a basic set of CRUD (create, read, update, delete) actions, along with some metadata actions to retrieve information about the structure of the entity.

API Explorer

The easiest way to see which actions are available for each entity is to browse the API Explorer, which shows all available entities, their actions, and the parameters for each action.

Most entities support the following actions:

Read Actions

  • get

    Search for records using SQL-like parameters (select, where, having, join, orderBy, limit). For most entities, get includes advanced features such as joins.

  • autocomplete

    Used to populate EntityReference autocomplete results, this action calls SearchDisplay::run which in turn calls the get action.

  • export

    Available only for Managed Entity types, outputs code which can be used to package and distribute a record in an extension.

Write Actions

  • create

    Insert a single new record into the database.

  • update

    Update one or more existing records with new values. If an id is not supplied, then query params are required to search for records to update.

  • save

    Given an array of records, either create or update each one. By default the presence of an id determines whether an existing record will be updated. The match param gives finer control over this, and lets you specify one or more fields; if a single existing record matches all of them, it will be updated instead of a new record created. For example you can save an array of contacts and specify ['external_id'] as the match param, which will update contacts with matching external_ids.

  • delete

    Delete one or more records based on query parameters. Some entities, including Contact, implement "Soft Delete", in which case the delete action's default behavior is to give records an intermediate "trashed" status. For these entities, set useTrash = FALSE to delete records permanently.

  • replace

    Replace an existing set of records with a new or modified set of records. For example, replace a group of Phone numbers for a given Contact.

Warning

Replace includes an implicit delete action - use with care & test well before using in production.

  • revert

Available only for Managed Entity types, resets a record to its original packaged state.

Metadata Actions

  • checkAccess

    Check if current user is authorized to perform a specified action on a given record.

  • getActions

    Returns a list of actions avaiable for a given entity.

  • getFields

    Fetch the list of fields supported by the entity, including custom fields. Optionally load the option-lists for fields.

Other Entity-Specific Actions

Some entities provide extra actions. For example, Afform::submit or SearchDisplay::run. To discover all available actions for an entity, use the getActions API action.